02 Nov 2020

REST API

REST (Representational State Transfer) API is a set of rules and conventions for building and interacting with web services.

Best Practices

Use JSON for Sending and Receiving Data

  1. In the past XML or HTML was used. With XML it was a bit of a hassle to decode and encode data.
  2. To ensure the client interprets JSON correctly you should set the Content-Type to application/json (many frameworks do this automatically).

Use Nouns Instead of Verbs

HTTP methods already use verbs like “GET” and “POST”. An example endpoint should look like this:

https://website.com/posts

Not like this:

https://website.com/getPosts

Name Collections with Plural Nouns

Do this:

https://website.com/post/1234

Not this:

https://website.com/posts/1234

Use Status Codes for Errors

Here’s a cheat sheet.

Use Nesting on Endpoints to Show Relationships

https://website.com/posts/postId/comments

Use Filtering, Sorting and Pagination

Retrieving data from a database can be slow. Use filtering, sorting and pagination to only retrieve the data that you need. 

https://website.com/posts?tags=cheatsheet

Use SSL

HTTPS should be used instead of HTTP for all requests and responses.

Clear Versioning

REST APIs should have different versions so that you don’t force your users to migrate to new versions.

Documentation

The documentation should contain: → relevant endpoints → example requests → implementation in several programming languages → messages listed for different errors with their status codes