Welcome!

Microservices Expo Authors: Elizabeth White, Liz McMillan, Pat Romanski, Anders Wallgren, AppDynamics Blog

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
With an estimated 50 billion devices connected to the Internet by 2020, several industries will begin to expand their capabilities for retaining end point data at the edge to better utilize the range of data types and sheer volume of M2M data generated by the Internet of Things. In his session at @ThingsExpo, Don DeLoach, CEO and President of Infobright, will discuss the infrastructures businesses will need to implement to handle this explosion of data by providing specific use cases for filte...
SYS-CON Events announced today that Avere Systems, a leading provider of enterprise storage for the hybrid cloud, 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. Avere delivers a more modern architectural approach to storage that doesn’t require the overprovisioning of storage capacity to achieve performance, overspending on expensive storage media for inactive data or the overbuilding of data centers ...
SYS-CON Events announced today that Commvault, a global leader in enterprise data protection and information management, has been named “Bronze 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, and the 19th International Cloud Expo, which will take place on November 1–3, 2016, at the Santa Clara Convention Center in Santa Clara, CA. Commvault is a leading provider of data protection and information management...
SYS-CON Events announced today that Alert Logic, Inc., the leading provider of Security-as-a-Service solutions for the cloud, 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. Alert Logic, Inc., provides Security-as-a-Service for on-premises, cloud, and hybrid infrastructures, delivering deep security insight and continuous protection for customers at a lower cost than traditional security solutions. Ful...
SYS-CON Events announced today that Interoute, owner-operator of one of Europe's largest networks and a global cloud services platform, has been named “Bronze Sponsor” of SYS-CON's 18th Cloud Expo, which will take place on June 7-9, 2015 at the Javits Center in New York, New York. Interoute is the owner-operator of one of Europe's largest networks and a global cloud services platform which encompasses 12 data centers, 14 virtual data centers and 31 colocation centers, with connections to 195 ad...
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,...
In most cases, it is convenient to have some human interaction with a web (micro-)service, no matter how small it is. A traditional approach would be to create an HTTP interface, where user requests will be dispatched and HTML/CSS pages must be served. This approach is indeed very traditional for a web site, but not really convenient for a web service, which is not intended to be good looking, 24x7 up and running and UX-optimized. Instead, talking to a web service in a chat-bot mode would be muc...
More and more companies are looking to microservices as an architectural pattern for breaking apart applications into more manageable pieces so that agile teams can deliver new features quicker and more effectively. What this pattern has done more than anything to date is spark organizational transformations, setting the foundation for future application development. In practice, however, there are a number of considerations to make that go beyond simply “build, ship, and run,” which changes ho...
WebSocket is effectively a persistent and fat pipe that is compatible with a standard web infrastructure; a "TCP for the Web." If you think of WebSocket in this light, there are other more hugely interesting applications of WebSocket than just simply sending data to a browser. In his session at 18th Cloud Expo, Frank Greco, Director of Technology for Kaazing Corporation, will compare other modern web connectivity methods such as HTTP/2, HTTP Streaming, Server-Sent Events and new W3C event APIs ...
SYS-CON Events announced today that AppNeta, the leader in performance insight for business-critical web applications, will exhibit and present at SYS-CON's @DevOpsSummit at Cloud Expo New York, which will take place on June 7-9, 2016, at the Javits Center in New York City, NY. AppNeta is the only application performance monitoring (APM) company to provide solutions for all applications – applications you develop internally, business-critical SaaS applications you use and the networks that deli...
Microservices are all the rage right now — and the industry is still learning, experimenting, and developing patterns, for successfully designing, deploying and managing Microservices in the real world. Are you considering jumping on the Microservices-wagon? Do Microservices make sense for your particular use case? What are some of the “gotchas” you should be aware of? This morning on #c9d9 we had experts from popular chat app Kik, SMB SaaS platform Yodle and hosted CI solution Semaphore sha...
Microservices are a type of software architecture where large applications are made up of small, self-contained units working together through APIs that are not dependent on a specific language. Each service has a limited scope, concentrates on a specific task and is highly independent. This setup allows IT managers and developers to build systems in a modular way. In his book, “Building Microservices,” Sam Newman said microservices are small, focused components built to do a single thing very w...
How is your DevOps transformation coming along? How do you measure Agility? Reliability? Efficiency? Quality? Success?! How do you optimize your processes? This morning on #c9d9 we talked about some of the metrics that matter for the different stakeholders throughout the software delivery pipeline. Our panelists shared their best practices.
The (re?)emergence of Microservices was especially prominent in this week’s news. What are they good for? do they make sense for your application? should you take the plunge? and what do Microservices mean for your DevOps and Continuous Delivery efforts? Continue reading for more on Microservices, containers, DevOps culture, and more top news from the past week. As always, stay tuned to all the news coming from@ElectricCloud on DevOps and Continuous Delivery throughout the week and retweet/favo...
The cloud promises new levels of agility and cost-savings for Big Data, data warehousing and analytics. But it’s challenging to understand all the options – from IaaS and PaaS to newer services like HaaS (Hadoop as a Service) and BDaaS (Big Data as a Service). In her session at @BigDataExpo at @ThingsExpo, Hannah Smalltree, a director at Cazena, will provide an educational overview of emerging “as-a-service” options for Big Data in the cloud. This is critical background for IT and data profes...
In a previous article, I demonstrated how to effectively and efficiently install the Dynatrace Application Monitoring solution using Ansible. In this post, I am going to explain how to achieve the same results using Chef with our official dynatrace cookbook available on GitHub and on the Chef Supermarket. In the following hands-on tutorial, we’ll also apply what we see as good practice on working with and extending our deployment automation blueprints to suit your needs.
Father business cycles and digital consumers are forcing enterprises to respond faster to customer needs and competitive demands. Successful integration of DevOps and Agile development will be key for business success in today’s digital economy. In his session at DevOps Summit, Pradeep Prabhu, Co-Founder & CEO of Cloudmunch, covered the critical practices that enterprises should consider to seamlessly integrate Agile and DevOps processes, barriers to implementing this in the enterprise, and pr...
If we look at slow, traditional IT and jump to the conclusion that just because we found its issues intractable before, that necessarily means we will again, then it’s time for a rethink. As a matter of fact, the world of IT has changed over the last ten years or so. We’ve been experiencing unprecedented innovation across the board – innovation in technology as well as in how people organize and accomplish tasks. Let’s take a look at three differences between today’s modern, digital context...
Sensors and effectors of IoT are solving problems in new ways, but small businesses have been slow to join the quantified world. They’ll need information from IoT using applications as varied as the businesses themselves. In his session at @ThingsExpo, Roger Meike, Distinguished Engineer, Director of Technology Innovation at Intuit, showed how IoT manufacturers can use open standards, public APIs and custom apps to enable the Quantified Small Business. He used a Raspberry Pi to connect sensors...
The principles behind DevOps are not new - for decades people have been automating system administration and decreasing the time to deploy apps and perform other management tasks. However, only recently did we see the tools and the will necessary to share the benefits and power of automation with a wider circle of people. In his session at DevOps Summit, Bernard Sanders, Chief Technology Officer at CloudBolt Software, explored the latest tools including Puppet, Chef, Docker, and CMPs needed to...