A professionally developed API is undoubtedly an asset to the organization responsible for its development and those who use it. Even though API design is considered important, minimal emphasis is given to the subject. This article will discuss the steps required to design a great API that can be applied to any project and industry.
Define an Objective
Why are you designing an API in the first place? What problems will it solve for you or the organization? This is the first step to creating an API. The steps you outline can be helpful when it comes time to document the API. Having a clear objective helps you chart a route for how the API will be designed and developed. It also helps if you use an API design tool which further streamlines the process.
Consistency and Stability
Any developer who has ever used Facebook’s API knows how frustrating it is because they redo the entire API from scratch. However, they are still successful, primarily because of over a billion users on their platform. Most people reading this article have nowhere near as many users, so your API must be a lot less volatile. The key is to continue supporting the older version for a longer time.
Let’s say tou have an API accessible via https://myapi.com/API; its response is JSON. What happens when you want to modify the format of the response? Naturally, everyone who uses the API will end up with a fragmented response.
Planning everything and starting to version your API from the beginning is important. Use a version number inducted into each URL, for instance, https://myapi.com/api?versioin=2. So, people can continue using the old API and then, later on, consider whether it is worth moving to the newer version. Then, when enough people have moved to the newer version, the older one can be phased out gradually.
Use Strong Terms
If your API starts to take off, expect to use many repetitive terms. Some actions, for instance, will be used several times and in different places, resulting in various types, methods, and classes; these may only subtly differ in behavior. If they are similar, then that should be reflected in their names. Use strong terms for each name. For instance, regardless of how a statement is executed, JDBC has to use the term ‘execute.’
Use Symmetry for Term Combinations
Once strong terms have been established, it is time to combine them. An excellent place to look at how this is done is JDK’s API collection. It is hard not to notice the fact that they happen to be symmetric in such a way that they have established terms like contains(), remove(), and add() before combining them symmetrically with add All(Collection<? Extends E>), Contains(Object), etc.
Consistency with Argument Ordering
It is important to be consistent with othe order aof arguments parts of your methods. It is a self-explanatory step for overloaded methods since it allows you to instantly see how much better it would be putting the array first, followed by the int.
Always Have Return Value Types
We may be getting into controversial stuff here because of opposing views. However, your API should consistently define return value types regardless of your opinion.
Final Word
A well-designed API can do a great deal of good for any business. However, developing it takes time and effort, not to mention expertise. Regardless of the industry, Joshua Bloch’s presentation (above) on API design is a great watch. It will step into what we have barely scratched the surface on in this article. If you are new to API development, this article is an excellent way to know where to start before coding.
