Best practices for REST API development
REST APIs were introduced somewhere around the year 2000. Over the years there have been many approaches regarding REST API development among the developer scene. However you should consider that REST is not a framework or will impose how you should create one, but is a design approach instead.
What I have been noticing myself is that various APIs have differences in usage here and there, and while it may work for you, keep in mind to give your users or developers a handy API they can utilise easily & comprehensible - otherwise they won't like using it!Here's what to keep in mind when developing a REST API:
1. Use JSON as a data format
You can send data in different formats like
CSV but the most common used data format is
JSON syntax is easy to use, provides easy parsing & fast execution of data, and the ability to prettify it makes it human-readable.
Additionally it has a wide range of supported browser compatability.
2. Use Nouns
You should avoid using verbs for enpoint names and use nouns instead.
To invoke actions, HTTP methods are used which are already tell you about the operation that is going on (e.g.
PATCH). These will be the major factor in defining how the endpoint is going to be used.
3. Use Plurals
Your data is a collection of resources. Meaning you will probably have multiple collections with multiple elements.
It is not only good development practice but also helps your users understand what's in the endpoint.
4. Nest logically
Depending on your usecase it is advised to group accociated information in a sort of hierarchy together.
This is good practice wheter your data in your database is structured the same way or not.
Actually, mirroring your database structure for your endpoints can give cool hackers (like me 😎, especially the cool part) too much information. So, avoid that.
5. Use Error Codes
The famous ERROR 404
Use HTTP error codes preferably with error messages in any response and request.
They are easy to read for machine and humans alike but might not always show the exact information.
Extend your information with appropriate error messages like Twilio does:
6. Allow filtering, sorting & pagination
Some users might want to sort a list of movies on a movie site by release date or name.
Imagine going onto a site like Netflix (or something similiar) looking for new movies. You'll check the movie tab out and filter by genre.
- filters for query parameter (movie gerne in this example).
- limits number of elements on the page
- sorts movies in an ascending order (alphabetically, for instance)
When creating APIs you will most certainly add more options, new methods or even change data structures. You may give your users the option to not adapt the latest API if an older versions also suits them.
Give your users a way to understand your API! I remember having to utilise an API for automating a CRM (Customer Relationship Management) tool which had a disatrous documentation, if any at all. And sitting through each and every call while trying to figure out how it's working and it's resources are structured was a big hassle and time waste.
a. Keep it simple
Make your API documentation comprehensible. Pick up the readers as if they had no knowledge of this at all.
Mailchimp has a really good documentation as well. Check it out
b. Show examples
Poeple learn best best with an example, so give them one. Easy as that.
Communication between the client and server should be private as it may contain confidential information. Users must not get more access to information than they requested. For example a normal user should not be able to access info from another user, or an admin especially. Enforce the principle of last privilege.
Dont' be one of those dinosaurs with Windows StoneAge. Use the latest security standards!
It should always be used. Please do not compromise your data. NO EXCEPTIONS!
Maybe consider using an SSL certificate, they are relatively cheap for what they offer.
10. Cache data in frontend
Instead of querying for data many times, use caching. The pro about caching is that users can get data faster. However, the data that users get may be outdated. This may also lead to issues when debugging in production environments when something goes wrong as we keep seeing old data, so keep that in mind.