Good RESTful API and How We Create It

Disclaimer: in this article, we decided not to dwell on the technical details of building a good API. If you are an API newbie from the technical perspective, consider the API design article by Microsoft — it covers the essentials of RESTful API development in all of the possible details.

Instead, we looked at the API from the usability perspective and compiled a checklist for you to ensure that your API is easy-to-use and secure.

So, check whether your API (is)…

...RESTful

It is obvious that your API should comply with the best practices of API design. There are lots of articles covering the topic: for example, you can refer to the Microsoft REST API Guidelines. You can also check how mature your RESTful API is by using the maturity model by Leonard Richardson. It is well-described in the Richardson Maturity Model article by Martin Fowler.

...Well-documented

API without documentation is a no-go — your engineers won’t simply get a clue of how to use it in the projects. To create comprehensive API documentation, we at Yellow use Swagger. It features the Swagger Editor tool that enables you to describe the API interface before actually coding it, and automatically generates the documentation for the API described. The main thing is that the documentation generated by Swagger Editor is self-renewing. As far as something is changed in the API description, the documentation also gets updated. Therefore, we avoid inconsistencies in our projects and make sure that our API documentation is always up-to-date.

Another reason that we use Swagger is Swagger Codegen. It enables you to generate server interfaces and client libraries that can be further used in the project. This tool saves engineers from the routine work of developing the server and client from scratch and helps you avoid the associated mistakes.

...Supports versioning

After your product is launched, you need to realise that not all of your users will be able to immediately upgrade to the latest version of your app. It is highly possible that many people will stick to an older version, at least for a while.

For example, suppose that you released a new app version for iOS 12. The users who haven’t upgraded to the latest OS yet or those with older gadgets won’t be able to use the new version — so they will stick to the previous one. In case your API supports versioning, there’s nothing to worry about — older versions are going to work fine. Otherwise, they will simply be crushed after a new version is released.

There are lots of methods to enable versioning support, they are well-described in the API design article by Microsoft. We prefer to use the URI method, which is mentioning the API version in the URIs of the API endpoints.

..Supports throttling (overload protection)

You should seriously think about introducing a throttling mechanism if you are going to give access to your API to third party engineers. Among them can be evil or unprofessional users who can waste your resources ineffectively.

For example, suppose that you developed a public API for a currency exchange service. A developer used it in their website and set it to update the exchange rate every time any user loads the webpage. This can impose a high load on your server.

To save your servers from overload, you should provide your API with a protection mechanism. One of the options is to set limits for the number of requests a user will be able to make per minute. If the user exceeds the limit, your servers will simply stop responding.

To implement this mechanism, you should be able to identify those who misuse your resources. For this purpose, user authentication is the right choice. Whether it is based on user credentials or unique API Keys, it will help you identify an evil user and temporarily block them from using your services.

...Secure

Although the user authentication mechanism protects your API from being misused, it should also be designed in compliance with certain security standards. We call them REST Security Basics; check out our article in which we cover the topic of implementing user authentication in more detail.

And, of course, your API should be covered by the HTTPS Protocol. Therefore you’ll make sure that all communication between your servers and multiple clients is encrypted both ways.

...Supports monitoring

There is nothing ideal in the world, and your API is no exception. Therefore it is highly possible that some unexpected errors will occur in your API once in a while. And you definitely want to learn about them immediately, don’t you?

To resolve arising issues in a timely fashion, there should be monitoring tools embedded in the API. The options you can use include Sentry.io, New Relic, and Zabbix, just to name a few. These tools will detect issues and notify you via email, Slack, or whatever you want. Just like that — you get all you need to deal with the issues until they deal with your app.

Final word

Let’s recap. To make sure your API is usable from the engineering perspective, please check if it:

If you checked all of the boxes — congrats, your API is perfect!

That was a quick guide on how to find out if your API is good in terms of usability. How many boxes have you checked?

✔Read also:

Advantages of Elasticsearch for Your Project

How to Build a Money Transfer Website: Guide and Interesting Stats