A professionally developed API is undoubtedly an asset to the organization responsible for its development, in addition to ones that use it. Even though API design is considered important very little emphasis is given to the subject. In this article we will discuss the steps required to design a great API which can be applied to any project and to any 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 out a route so to speak 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 just how frustrating it is because each time they redo the entire API from scratch. However, they are still successful, and that’s primarily because of over a billion users on their platform. Though most people reading this article have nowhere near as many users, so it is essential that your API be a lot less volatile. The key is to continue supporting the older version for a longer time.
Let’s say that you have an API that is accessible via https://myapi.com/API, and its response is in JSON format. Though what happens when you want to modify the format of the response? Naturally, everyone who is using the API will end up a fragmented response.
It is important to plan everything ahead start versioning your API from the very beginning. Make sure to use a version number which is 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 if 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 that there will be a lot of repetitive terms used. Some actions, for instance, will be used several times and in different places which results 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, JDBC, regardless of how a statement is executed you have 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() prior to combining them symmetrically with add All(Collection<? Extends E>), Contains(Object), etc.
Consistency with Argument Ordering
It is important to be consistent with order arguments part of your methods. It is a very obvious 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
Now we may be getting into the realm of controversial stuff here because there are opposing views on the topic. Though regardless of your opinion, your API should be consistent when it comes to the ability to define return value types.
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. Though if you are new to API development, this article is an excellent way to get an idea of where to start before you begin coding.