A Look At Pragmatic API Design
Now once an API developer has a stable data model the next step is to create an API that’s public or otherwise for the web application. Many look at this as being the next logical step in the development phase.
Though once the API becomes available to the public making changes to it can be near impossible. So, the only way you can get around this is to start with a solid API design concept and then plan things from there onwards.
The internet is littered with articles and forum posts expressing various personal opinions about API design methodology which can all be right as much as they can all be wrong. The reason being that there isn’t one right way to do it.
Take for instance what authentication will you use? Which formats are accepted etc.? The goal of this article to help answer some of these questions in the most straightforward way as possible.
What Does an API Require?
We did a bit of research before writing this article, and it was clear that most opinions expresses are impractical academic ones.
Most of which revolve around using fuzzy logic or some other subjective standard. Much of what we ran into cannot be easily implemented in the real world. So, let’s start with outlining the best practices of designing an API.
We must also state at this point that our intent isn’t to sell you a set of standards or development methodologies. Below is a list we’ve put together which we think APIs should meet in terms of requirements:
- Has to make use of sensible web standards
- The API needs to be developer friendly, and so it also has to be easily explorable via a web browser
- An intuitive, consistent and simple design will encourage adoption
- The API needs to be powerful and flexible making it compatible with many UIs
- The required API also needs to be efficient yet maintain a right balance between usability and meeting standards
Because APIs are meant for developers, it needs to provide excellent user experience and support.
Make Use of SSL Certificates
Many developers including ourselves stand strongly behind the use of SSL certificates. Web APIs are accessed by millions of people connected through various interfaces and public networks like in coffee shops, airports, and libraries.
Since these networks are not always secure and don’t even encrypt information, this makes it easier for hackers to easily eavesdrop and even impersonate an individual using forged certificates.
The other incentive to use SSL certificates is that it guarantees encryption for all types of communication and it also makes authentication smoother. So, it is possible to get away with using simple access tokens and not just needing to file every request with the required API.
What APIs need to handle is the non-SSL access. You don’t want any direct requests to the SSL counterparts but on the contrary, offer an error. Obviously developers shouldn’t be encouraged to send you poorly configured requests to a point which isn’t encrypted.
Proper Documentation
An API is only as good as the way in which it is documented. The documents make it easy for developers to understand its implementation. Developers make it a habit to check the documents before undertaking integration. You shouldn’t make the docs hard to reach by making signing in mandatory as it makes it difficult for search engines like Google and Bing to index them.
Final Word
After an API goes public, you need to commit to not changing any aspect of it without proper notification. The updated documentation needs to be highly detailed.
