Once you have a stabilized data model, it is time to create a public API for the web app. It is often considered the next step. However, it is also worth noting that once your API is released to the public, it can be near impossible to make significant changes. The only way to get around it is to use a solid design platform and plan for everything upfront. The internet is full of various opinions about API design methodology but because there is no single widely adopted standard you have many different choices. For instance, what formats should you accept? How will authentication work? Do you need to version the API? As API designers ourselves working on dozens of projects each year, our goal is to answer some of these questions as clearly as possible.
What is Required for the API?
If you search the internet for information on API design the vast majority of opinions are academic ones which revolve around mainly fuzzy or subjective standards. Most of what they discuss isn’t implemented or possible to apply in the real world. So, to start with, we need to outline the best practices when designing a pragmatic API. Our attempt here is not to sell you a standard but tell you what works. Below are a couple of requirements that an API should meet:
- It needs to use sensible web standards
- The API should be developer friendly and easy to explore via a web browser
- The design needs to be intuitive, simple and yet consistent which makes adoption easy
- It needs to be flexible so as to power the vast majority UIs
- The API should be efficient while at the same time be able to maintain a balance with other requirements
Since an API is meant to be used by a developer, i.e. a developer’s UI, it has to provide a great user experience.
Using SSL Certificates
We and many other API developers strongly stand by the fact that SSL is essential and there should be no compromises here. Today’s web-based APIs are accessed from millions of connected computers, many of which are connected to public networks like at airports, libraries and coffee shops, etc. Not all of these networks are obviously secure, and many don’t even encrypt the information at all which makes it easier for hackers to eavesdrop or even start impersonating an individual with forged credentials.
The other significant advantage of always sticking with SSL is that you’re guaranteed encryption for all communication, and it makes authentication easier. So, you can get away with using those simple access tokens instead of having to file each request with the API.
However, what you need to be able to handle is non-SSL API access. You don’t want to direct these requests to their SSL counterparts but instead return an error. You don’t want developers sending your API poorly configured requests to an endpoint that isn’t encrypted.
Detailed Documentation
In our experience, any API you use is only as good as how well it is documented. The documents need to be easy to find by developers. Developers will always check the docs before attempting an integration. But when you hide the docs inside of a PDF file, or you make it mandatory to sign-in, it makes it difficult to find as it will not pop up in search engines.
It is also imperative for the documentation to show instances of response and request cycles. You can check out Stripe and GitHub’s API for a good example.
Conclusion
Once your API goes public, you have to commit to not changing things without prior notice. The documentation needs to detail everything. You’re not Facebook and so if things break developers will not give you a free pass.
Be First to Comment