.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 HTML, XML and CSV but the most common used data format is JSON.

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. GET, POST, PUT, PATCH). These will be the major factor in defining how the endpoint is going to be used.

Example:

Avoid this! (the 'get' in '/getUser' is kind of redundant here..)

Use this instead

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.

EXAMPLES:

While this is somehow okay (not really), it does not show that there are other items (movies) in your collection

Here it is apparent that there are multiple movies

4. Nest logically

Depending on your usecase it is advised to group accociated information in a sort of hierarchy together

Every user seems to have an order collection

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:

Twilio uses their own internal codes with error messages

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.

EXAMPLES:

Filtering: https://mywebsite.com/movies?gerne=action

• filters for query parameter (movie gerne in this example).

Pagination: https://mywebsite.com/movies?limit=10

• limits number of elements on the page

Sorting: https://mywebsite.com/movies?sort=ascending

• sorts movies in an ascending order (alphabetically, for instance)

7. Versioning

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.

The sense of freedom

8. Documentation!

WRITE DOCUMENTATION!

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.

9. Security

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!

a. HTTPS

It should always be used. Please do not compromise your data. NO EXCEPTIONS!

b. SSL

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.