This is an exciting time for developing and rolling out APIs. The change in the consumer behavior and the explosion of the app markets has opened up new avenues for businesses to share and monetize information & services. APIs have a tremendous role to play in that space. Developing APIs can get a little tricky particularly if it’s your first time. Based on our experience in developing APIs for clients from different domains, we have distilled 6 tips that can make API development experience painless and fruitful.
Tip #1 – Simulate First!
Any one who has been through an API integration project can tell you how much pain a simple task like integration can generate. Sure, you can document the API specifications and socialize it with everyone who needs to eventually integrate. But documentation gets ignored – developers don’t give as much importance to writing documents and keeping them updated as they should. On the receiving side too, the developers will read it; even come back with some comments or changes but that’s about it. When they start writing their integration glue the document will be out of date and fairly inaccurate.
In our experience getting a dumb stub of your service up as early as possible and sharing its URL with everyone who needs to integrate can go a long way in alleviating the integration pain. You will still need to supplement it with a document but now you are also handing out something that works, something that the developers can play with. The stub does not need to have the actual API logic implemented. It is okay for it to return same fixed values for every request (or you can write two responses and randomly return one of them if you are feeling generous). Since the other party develops to an integrate-able code early in the development, there will be limited surprises towards the end of implementation. This is very helpful when developing B2B APIs.
Tip #2 – Cache That Response
Any good developer knows that caching infrequently changing data in applications can significantly improve application performance. In a similar manner, an API’s performance can be improved dramatically by caching infrequently changing responses. For instance, if you are developing an API that gives out temperature at a particular location then you can cache that response and return the same for subsequent requests for the same location for say the next thirty minutes. Temperatures do not change that frequently so as long as you get the same location in the request, you can return the same response without even going to the application layer.
Though many developers focus on application caching, API response caching is not that common. It is probably because when you create an API, in your mind you are creating something that reports ‘something current’ to someone outside the system. In reality, it is very contextual. Of course, you will never cache response of an API that returns financial information. But in a lot of scenarios, this can add significant value to the performance and operational costs of running APIs.
Tip #3 – Factor API Versioning
Like any other software, APIs also evolve with time. The tricky part with APIs as compared with other software is that APIs involve at least one more consumer who will be affected by any change in the API signatures. If your APIs are popular then you potentially have thousands of consumers who will be affected by the change. Managing API evolution can be troublesome if versioning is not factored in from day one.
APIs that are in active use need to support multiple versions at some point during their lifecycle. A popular means of accommodating versioning is including it in the API signature. For instance:
Some people prefer hosting different versions on different URLs. It might make sense in some exceptional cases but in general, it is a bad idea because of operational overheads and issues. Irrespective of how you implement it, you should factor in API versioning in your development plan for a painless evolution of your APIs.
Tip #4 – Defaults
One of the key influencers of success of APIs are developers. APIs that make developers job easy and are not a hassle to integrate with have a higher chance of succeeding. APIs that are simple and easy to use earn developers nod quickly. Even if an API has to be complex, it should at least be flexible to configure and get a response.
Keeping defaults is one of the ways to simplify a request. An API request may depend on multiple input parameters for providing meaningful response. However, during the initial API trial, it should not be relevant or necessary for a developer to understand all the parameters and their usage. The initial instinct of a developer is to get a successful response – any successful response – out of an API as quickly as possible.
Once an API gives a successful response, the developer feels more confident and encouraged to use it. But if it takes lot of reading and understanding just to get started with an API, it pushes developers away.
For instance, if “Accept” header is not specified in a request then default the response can be considered JSON. Now we are not advocating that you go on defaulting every input parameter. An API may need some minimal input parameters to return a meaningful response. Something like a customer id cannot be defaulted. But you should considering accepting defaults for parameters that have limited set of values – things like request headers, output formats, versions, etc. Take the most used parameter value by default if it is not provided in the request. Not only does this simplify working with the API, it also increases the performance because of the reduced payload size.
Tip #5 – Rate Limiting
APIs are also prone to Denial-of-Service (DoS) attacks like other publicly available resources. Here is a recent reference to one such attack:
This can be particularly damaging if your APIs share infrastructure with other applications. An API under attack can bring down all the components that share its infrastructure resources. While there are specialized tools available to manage these attacks, you can also build basic scrutiny in your API through rate limiting. Rate limiting is a simple concept of controlling who gets to call an API and how many times in a given time window. You can rate limit by IP address or by user if your APIs authorize users.
Another important aspect of rate limiting is creating a facility to ignore all requests coming from a given IP address or a particular user or to a particular API method. This will give you the ability react to an API DoS attack.
Tip #6 – Wrap It All Up!
The easiest and most efficient way of implementing the above five tips is by creating a wrapper around your API layer which can take care of services like caching, stubbing, versioning, defaulting and rate limiting. Not only will this keep your actual API light, it will also give you flexibility to re-use this layer across multiple APIs. Depending on your budget and need, you can either design a wrapper on your own or buy some of the commercial off the shelf API wrappers and management platforms.