Best Practices for Rest API
Reaching the point of working on a stable platform is a beautiful feeling. So much so that programmers, naturally get the inclination that creating a publicly accessible API is the way to go. It gives your users a chance to do more without all the hardships involved in having to scrape your web apps for pipeline data.
These days there’s no shortage of publicly accessible API’s. Having had the opportunity to work and experiment with a handful of them, it’s apparent that many are poorly designed and dependent on constant manual changes or adjustments. The same goes for an overall lack of validation, and thin documentation which doesn’t help developers to understand how the API works and its use cases.
Today, we will focus on RESTful API best practices. The notion of REST is to separate the API structure into logical resources. These are used by the HTTP methods GET, DELETE, POST, PATCH and PUT to operate with those resources.
Nouns vs. Verbs
If you are to design RESTful API’s, always remember: Keep stuff simple. In this case, don’t overcomplicate your base URL’s and make them intuitive instead.
Using HTTP methods to interact with your resources saves you time, promotes productivity, and generally easier to manage long-term.
Using the URL, you can specify the resource that you want to operate with (e.g employees) and the HTTP methods allow you to perform actions. This is also known as the CRUD (Create, Read, Update, Delete) approach, where you take advantage of the GET, POST, PUT, and DELETE methods.
Philipp Hauer wrote an in-depth guide on how to use nouns and plurals for designing an optimal and design-friendly RESTful API.
Secure your API using SSL, always
In the modern world, users can access the internet from virtually anywhere. This means that users could be accessing your API from locations that aren’t necessarily secure by themselves, like airports, public restaurants, and libraries. It’s possible that these users could end up leaking sensitive data over unencrypted communication channels.
Using SSL for your API solves another very apparent problem: The need to sign individual API requests, versus being able to use access tokens to authenticate users.
Think twice before you publish
Once you have published your API, you shouldn’t introduce any operation-level changes in a production environment. For one simple reason: You will break everyone’s environment for using the API.
Fixing bugs is perfectly fine unless you are changing the very structure of how the API works. If you plan to make significant changes to the way that the API functionality operates (in particular, the endpoints), then it is essential to inform all the API users about the coming changes. Think of it this way: A small and unexpected change could potentially break every single application relying on the API because the fundamental structure has been altered. Without a doubt, that’s a poor business decision.
Version your API from the beginning
The immediate fix to the problem above is be versioning. Your business operations are eventually going to change. The same goes for giving users new information as they request it. Using version URL structure for your API right from the start is going to keep away those nasty headaches when the time comes to change things up.
The most commonly used process of API versioning is to append the version of the API that’s currently in line with your production software:
https://yourwebsite/api/v1/customers/1234
https://yourwebsite/api/v2/customers/1234
https://yourwebsite/api/v2.2/customers/1234
Head over to this StackOverflow thread to learn more about the best practices for API versioning. It covers many different contexts, far too many to include in a post of this length!
Your API is as good as the documentation
Document everything. Not only will it help to avoid continuous stream of questions from developers who don’t understand some specifics about your API, it will encourage for developers to use it more properly and to its fullest potential; the intended purpose of it.
The first place developers will go to when starting to implement your API is the documentation, so you must put in the effort to create a documentation that covers not only the names of the endpoints you are using, but also the full complexity of queries and strings that you are proposing with your API.
Dropbox and Uber are good example documentations to give you a hint as to how to structure your own. You can also try using an open-source library like apiDoc which can generate documentation for you.
Handle Errors using HTTP response codes
Exceptions will be thrown and the only way to understand them properly is through proper using of HTTP response codes. There are more than 70 response codes, and you don’t have to utilize them all. Here are a few essential ones that definitely improve the Client-to-API interaction experience.
Here is a handful of them:
- 200 – OK – Working as intended
- 201 – OK – Resource creation successful
- 204 – OK – Resource deleted successfully
- 304 – Not Modified – The client can use cached data
- 400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid“
- 401 – Unauthorized – The request requires an user authentication
- 403 – Forbidden – The server understood the request, but is refusing it or the access is not allowed.
- 404 – Not found – There is no resource behind the URI.
- 422 – Unprocessable Entity – Should be used if the server cannot process the entity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
- 500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the stack-trace should be logged and not returned as response.
This way, developers can quickly identify and debug the problem if one arises.
Additional Resources
Looking for more inspiration to create a RESTful API? Check out these great articles on Spring and Heroku.
