Web API Design Part Ten: Management

20 Dec

Episode 96

It’s been a while, but I’m back with the next installment of API design series. Today we will step away a bit from technicalities and jump into the business perspective. After all, API is a product and needs to be treated as such. As we discussed one year ago in the first chapter of our journey, API is for developers as a graphical user interface is to regular software users. It’s a gateway to business value. And there are quite a lot of issues going around the product to think about and to be aware of.


Image by Cosmic Net Studios

API management is a process of creating, publishing, enforcing usage policies, taking care of subscribers, analyzing the traffic and monetizing our product. API is as successful as developers who build upon it. Much of API management effort is directed towards empowering developers that use the API and simplify their work as much as possible. Some aspects of API management are more technical than others and with the rise of API management platforms this tendency increases, as more features are delegated to the platform. We will focus on less technical issues today, starting with lifecycle management.


Every product, whether it is software or not, goes through similar phases of its existence. We start with an idea, do the market research whether there is a place for a product and whether someone else already came up with something similar. If the idea is promising we plan and start to develop the product. When it’s ready we launch the initial version (some companies have difficulty with the concept of ready). As time passes, we develop new versions and at some point, mark old versions as deprecated. After users have enough time to adapt to changes, we retire old version to lessen the burden of maintenance of multiple endpoints and clean up.  Versioning strategies were the topic of the previous article. All those steps require proper communication with our users so that they are not caught by surprise with sudden changes. Release notes of newer version should contain warning and timelines of incoming depreciations and retirement. It’s good to send release notes via email to our subscribers in order to increase the chance that the warning will be delivered. Another part of lifecycle management is the API roadmap that will highlight the direction in which the product is going and sketch the features that will be available in the future.


There are many ways to help developers use our API. Common idea is to host a developer portal that consolidates all important information and tools related to our product. Aside from formal documentation, we can post various tutorials, guides, best practices or other articles touching subjects that might be helpful for our users.  Written materials can be accompanied by videos, including records of conference talks. There might be a forum where users can post questions and look for answers either from our support staff or other users. Developers community topic reaches beyond simple forum, for instance into various social media platforms. We can further increase productivity offering a collection of SDKs for popular programming languages that would simplify development. There might be a command-line interface tool that translates commands into appropriate requests to our API that can be leveraged in scripts and other automation efforts. Let’s have a look at the documentation in more detail.


Image by Trung Tin Shinji


Documentation comes in many flavors. Most commonly we think about the exhaustive reference to each endpoint listing available HTTP methods, the structure of request and response, query parameters, headers, and possible response codes. Each of them should be thoroughly explained including the business concepts and rationale behind it. It’s best if such documentation is interactive – have a “try it out” button that would send a request that can be edited and a field to display result that comes from a testing server. The same content as we present in an interactive HTML form should be accessible as a standalone PDF file that can be downloaded and viewed offline later. Exhaustive reference is a bit like address book – useful but boring. A good companion would be a document that guides the developer through the business process steps and explains what’s going on step by step without getting too much into details. We can also add a quick start section in prominent place on the developer’s portal that would focus on getting us started with first requests. Another idea to support documentation is to as a Postman collection with the typical flow and pre-request scripts that will automatically carry relevant values between calls. For instance, if we perform a search for a train connection between two cities that result with an id of a trip or route, we can script this as a parameter that will automatically be used in the further call that reserves the ticket, without manual copying and pasting.


We might say that support saves the day where documentation fails. Indeed, good documentation and error handling might save us a lot of time answering the same questions over and over again, especially if we have a lot of users. But there are other things related to the support. For instance, provisioning – in case of more business-oriented APIs that do not have a lot of users to register, we might opt to have a manual keys provisioning – in order to get access to API the customer needs to contact support person, or key account manager if you will. Sometimes users run into problems that API creator haven’t anticipated, sometimes they find a bug or they would like to request a new feature. All that has to be managed in some way. Bad or slow support can be a major deterrent for many users.



Traffic flow needs to be controlled. We would like to know who is calling us and how often, and we would like to limit this accordingly to our business model. A common solution is to have a quota of calls per unit of time or two for an identified user. The first unit of time would be a day or month and it represents an amount of value user can get from our system, say 10000 requests per day. The second quota would be associated with a short time window, e.g. 100 requests per second. This would allow our system to respond consistently without limiting other users and protect it from DDoS attack. Traffic management also includes SLA on response time. And finally, we should think of all that aspects when making requests to third-party services that our system uses as a result of requests to our API.


Analytics is about understanding how our API is used and leverage this knowledge to improve the service. We would like to know where our users are when they are active and what they do. We want to know which services are most used, what are the behavior patterns, what data is popular. We can use that, for instance, to focus on particular markets or target groups and smartly support our marketing efforts. Having robust analytics might help us detect suspicious behavior and mitigate threats. The world is driven by data, and the more data we have to correlate the more value we can get out of it.


Last but not least, an API is a product and we build products in order to earn money, right? Racal the “Why, what and how” questions from the first chapter of our journey. There are several models of doing that. Some APIs are free. The aim for that is to build a developer community around our product, promote the brand or extend our capabilities of offering other services. For instance, a retailer or train operator would be happy to offer its products or tickets via another channel of distribution other than the website, and free API might be just that. We might even add an additional incentive to promote it. Popular API might also be a great source of data about its users that itself is a value, for example, a travel search engine operator gets an insight into the industry trends and sell this information to interested third parties. Other than that, if an API provides direct value to the customer, we can offer something for free to attract consumers to try it out. If they like it and want more, we can charge per call or offer various tiers of service with different quotas and additional levels of support.


Image by Miggs69

Control your Chaos

All that again seem like a lot of things to care about. Luckily, we don’t have to reinvent the wheel in most cases and we can turn to already existing solutions. Two years ago, I wrote about API management tools that can help us in all aspects I mentioned today and much more, including aspects mentioned in security and versioning chapters and others such as alerting, monitoring, prototyping and more. Developing API is not just programming and configuration work, there are many softer things around that and I believe it’s good to keep them in mind.

We are getting closer to the end of our API journey and I intend the next episode to be the last one of it. We will talk about all the things worth mentioning that I had difficulty to allocate to an existing chapter. Lots of tips and tricks under the umbrella of Miscellaneous. If you don’t know how to name a piece of knowledge, go with Miscellaneous. Merry Christmas, Happy New Year and stay tuned!

1 Comment

Posted by on December 20, 2018 in API, Technology


Tags: , ,

One response to “Web API Design Part Ten: Management

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: