Welcome!

Microservices Expo Authors: Elizabeth White, Liz McMillan, Jason Bloomberg, Anders Wallgren, Derek Weeks

Related Topics: Containers Expo Blog, Java IoT, Microservices Expo, Agile Computing, @BigDataExpo, SDN Journal

Containers Expo Blog: Blog Feed Post

Your API Requires What??

Stability and predictability of APIs is essential, without those items the toolset will not get used.

If you’ve ever developed for an enterprise IT department, and had to please the end user, you know very well that they don’t care about what your technical limitations are, they care about getting a tool that helps them do their job better. Oh some will commiserate with you about your challenges, and the best of the business side will compromise to get to a product that helps, even if it’s not perfect, but much like everyday consumers, they want what they want, and you either provide it or not. The thing is, in the enterprise, the pool of users is much smaller than for a commercial application, but the users are more focused on what they need, precisely because there are less of them.

On thing that many vendors fail to comprehend is that this “I need what I need and you provide it or you do not” approach applies just as strongly to enterprise developers. While most business to business (B2B) vendors (both hardware and software) understand the need to provide a useful, generally easy to learn user interface or command line, often that understanding does not extend to APIs.

Don’t make API consumers

into this guy.

There is a mentality of “We’re all developers here…”, which is true, but developers have different priorities. Just as the bulk of end users will not use an application that is poorly documented, non-intuitive, and complex, the same is true for the bulk of enterprise developers. They have a goal in mind, are trying to get their job done, and if your API is slowing them down or making their work harder, they will look for alternate ways to achieve their goals.

Oh, for sure there will be a small percentage that dig in and learn the API no matter how confusing and undocumented it is, for a variety of reasons ranging from earning geek cred to project requirements demanding it. But if given a choice, the vast majority of developers will seek an easier way to do what needs doing. They have timelines and deadlines, and will not let something like poor documentation interfere with those requirements.

Yes, stability and predictability of APIs is essential, without those items the toolset will not get used. But without documentation and an intuitive design with predictable types, requests, responses, etc. many developers won’t even get to the stability part. When the tool cannot be figured out in the time available, stability is entirely irrelevant.

So what do you need? Well, I have years of both writing and using APIs, and here are a few tips from me, no doubt others have a lot to add to the conversation:

  1. Cohesive design. Most APIs grow over time, but they need to adhere to standards set by the API docs, so that developers don’t waste time going “what is this completely different thing here…?” Variations need to be clearly documented.
  2. API reference. A quick reference to help developers understand how to make the API calls, what parameters are, what responses will be, standards supported, and requirements to use the API.
  3. A full blown “how to set this up”. Including clear documentation of the things required to use the API. Developers don’t care if you didn’t write part of the toolset – they expect that – but you’d better give them every bit of information they need to configure it for their development environment, including the parts you didn’t write. It’s your API, document all the steps to make it work.
  4. Samples. Not “Hello World” level, though that belongs in the API, but real use-case samples that delve in deep, preferably in steps so developers can learn without turning on the firehose.
  5. Input/output samples. In the world of SOAP/REST APIs, sometimes you just need to see what the final request going out needs to look like, and what to expect in the response document.
  6. High-level APIs. The more mondo-geeky your dev staff, the more likely that they want to expose each little tiny operation your product is capable of as a separate API. But honestly, enterprise developers don’t want to make 50 calls to do one thing common to their industry. It wastes time coding, it wastes network bandwidth, and it makes the application more laggy. To use my utility roots, if “Read a meter” is the command, THAT is what developers want to tell the API. They don’t (and shouldn’t have to) care how many steps that takes, they want the toolset to “just do it”. That is not to say that users do not want access to the individual steps of a process, only that they require one call to achieve one business function. If you don’t have a business layer, go write one. Now.
  7. Rockstar support. Seriously, if you want people to use the tool, then you have to give them a way to get solid answers. Places like StackOverflow are great for things a large number of people are using, but for your highly specialized API, not so much. So you have to provide it – in a community, with tech support, whatever way works best, but when stuck, people need their questions answered, not to paw through docs hoping to find some vague reference.
  8. Cohesive communications and constant feedback. Getting out there via social media, blogging, meetups, whatever, and talking about changes coming to APIs, new uses some customers have found for the APIs, bugs that are in-line to be fixed and workarounds are pretty darned important. Users want to be informed, and silence about the APIs kind of implies a lack of support going forward – whether that implication is accurate or not, it is perceived. And feedback is where the best ideas for improvements come from. The person who just struggled through implementation of the API for the first time has a unique view on what could be better, and needs a communications mechanism to make those recommendations. Meanwhile, the person whose dedicated a couple of years to production use of the API might well understand the real-world implications of the design better than the original analysts who wrote it up. Again, a feedback mechanism is required.

In the end, the point of an API is to get people to use it. Invest in the API, treat it like a product, even if in your business case it is a feature, not a product. It was developed for a reason, give IT the tools to make that reason real.

And save us all a ton of time trying to figure out how to use it, so we can focus on the overall application, not your tiny bit of it.

Read the original blog entry...

More Stories By Don MacVittie

Don MacVittie is currently a Senior Solutions Architect at StackIQ, Inc. He is also working with Mesamundi on D20PRO, and is a member of the Stacki Open Source project. He has experience in application development, architecture, infrastructure, technical writing, and IT management. MacVittie holds a B.S. in Computer Science from Northern Michigan University, and an M.S. in Computer Science from Nova Southeastern University.

@MicroservicesExpo Stories
You deployed your app with the Bluemix PaaS and it's gaining some serious traction, so it's time to make some tweaks. Did you design your application in a way that it can scale in the cloud? Were you even thinking about the cloud when you built the app? If not, chances are your app is going to break. Check out this webcast to learn various techniques for designing applications that will scale successfully in Bluemix, for the confidence you need to take your apps to the next level and beyond.
Digital means customer preferences and behavior are driving enterprise technology decisions to be sure, but let’s not forget our employees. After all, when we say customer, we mean customer writ large, including partners, supply chain participants, and yes, those salaried denizens whose daily labor forms the cornerstone of the enterprise. While your customers bask in the warm rays of your digital efforts, are your employees toiling away in the dark recesses of your enterprise, pecking data into...
SYS-CON Events announced today that DatacenterDynamics has been named “Media Sponsor” of SYS-CON's 18th International Cloud Expo, which will take place on June 7–9, 2016, at the Javits Center in New York City, NY. DatacenterDynamics is a brand of DCD Group, a global B2B media and publishing company that develops products to help senior professionals in the world's most ICT dependent organizations make risk-based infrastructure and capacity decisions.
With DevOps becoming more well-known and established practice in nearly every industry that delivers software, it is important to continually reassess its efficacy. This week’s top 10 includes a discussion on how the quick uptake of DevOps adoption in the enterprise has posed some serious challenges. Additionally, organizations who have taken the DevOps plunge must find ways to find, hire and keep their DevOps talent in order to keep the machine running smoothly.
Call it DevOps or not, if you are concerned about releasing more code faster and at a higher quality, the resulting software delivery chain and process will look and smell like DevOps. But for existing development teams, no matter what the velocity objective is, getting from here to there is not something that can be done without a plan. Moving your release cadence from months to weeks is not just about learning Agile practices and getting some automation tools. It involves people, tooling and ...
Between the mockups and specs produced by analysts, and resulting applications built by developers, there exists a gulf where projects fail, costs spiral, and applications disappoint. Methodologies like Agile attempt to address this with intensified communication, with partial success but many limitations. In his session at 18th Cloud Expo, Charles Kendrick, CTO & Chief Architect at Isomorphic Software, will present a revolutionary model enabled by new technologies. Learn how business and devel...
The notion of customer journeys, of course, are central to the digital marketer’s playbook. Clearly, enterprises should focus their digital efforts on such journeys, as they represent customer interactions over time. But making customer journeys the centerpiece of the enterprise architecture, however, leaves more questions than answers. The challenge arises when EAs consider the context of the customer journey in the overall architecture as well as the architectural elements that make up each...
APIs have taken the world by storm in recent years. The use of APIs has gone beyond just traditional "software" companies, to companies and organizations across industries using APIs to share information and power their applications. For some organizations, APIs are the biggest revenue drivers. For example, Salesforce generates nearly 50% of annual revenue through APIs. In other cases, APIs can increase a business's footprint and initiate collaboration. Netflix, for example, reported over 5 bi...
As the software delivery industry continues to evolve and mature, the challenge of managing the growing list of the tools and processes becomes more daunting every day. Today, Application Lifecycle Management (ALM) platforms are proving most valuable by providing the governance, management and coordination for every stage of development, deployment and release. Recently, I spoke with Madison Moore at SD Times about the changing market and where ALM is headed.
If there is anything we have learned by now, is that every business paves their own unique path for releasing software- every pipeline, implementation and practices are a bit different, and DevOps comes in all shapes and sizes. Software delivery practices are often comprised of set of several complementing (or even competing) methodologies – such as leveraging Agile, DevOps and even a mix of ITIL, to create the combination that’s most suitable for your organization and that maximize your busines...
These days I mostly make my living as a consultant. Consultants in general are probably not the best loved group in the world. It is common to think of consultants wafting-in to your organization, telling you things that you already know and advising you to “change your culture”, whatever that means. Subsequently they depart, no-doubt with a fat fee, and leave you as you were before with the same problems and no progress made.
Struggling to keep up with increasing application demand? Learn how Platform as a Service (PaaS) can streamline application development processes and make resource management easy.
In the rush to compete in the digital age, a successful digital transformation is essential, but many organizations are setting themselves up for failure. There’s a common misconception that the process is just about technology, but it’s not. It’s about your business. It shouldn’t be treated as an isolated IT project; it should be driven by business needs with the committed involvement of a range of stakeholders.
New Relic, Inc. has announced a set of new features across the New Relic Software Analytics Cloud that offer IT operations teams increased visibility, and the ability to diagnose and resolve performance problems quickly. The new features further IT operations teams’ ability to leverage data and analytics, as well as drive collaboration and a common, shared understanding between teams. Software teams are under pressure to resolve performance issues quickly and improve availability, as the comple...
The goal of any tech business worth its salt is to provide the best product or service to its clients in the most efficient and cost-effective way possible. This is just as true in the development of software products as it is in other product design services. Microservices, an app architecture style that leans mostly on independent, self-contained programs, are quickly becoming the new norm, so to speak. With this change comes a declining reliance on older SOAs like COBRA, a push toward more s...
Join IBM June 8 at 18th Cloud Expo at the Javits Center in New York City, NY, and learn how to innovate like a startup and scale for the enterprise. You need to deliver quality applications faster and cheaper, attract and retain customers with an engaging experience across devices, and seamlessly integrate your enterprise systems. And you can't take 12 months to do it.
This is not a small hotel event. It is also not a big vendor party where politicians and entertainers are more important than real content. This is Cloud Expo, the world's longest-running conference and exhibition focused on Cloud Computing and all that it entails. If you want serious presentations and valuable insight about Cloud Computing for three straight days, then register now for Cloud Expo.
The proper isolation of resources is essential for multi-tenant environments. The traditional approach to isolate resources is, however, rather heavyweight. In his session at 18th Cloud Expo, Igor Drobiazko, co-founder of elastic.io, will draw upon their own experience with operating a Docker container-based infrastructure on a large scale and present a lightweight solution for resource isolation using microservices. He will also discuss the implementation of microservices in data and applicat...
SYS-CON Events announced today that Stratoscale, the software company developing the next generation data center operating system, will exhibit at SYS-CON's 18th International Cloud Expo®, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. Stratoscale is revolutionizing the data center with a zero-to-cloud-in-minutes solution. With Stratoscale’s hardware-agnostic, Software Defined Data Center (SDDC) solution to store everything, run anything and scale everywhere...
SYS-CON Events announced today that Men & Mice, the leading global provider of DNS, DHCP and IP address management overlay solutions, will exhibit at SYS-CON's 18th International Cloud Expo®, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. The Men & Mice Suite overlay solution is already known for its powerful application in heterogeneous operating environments, enabling enterprises to scale without fuss. Building on a solid range of diverse platform support,...