Cheatography
https://cheatography.com
Cheat sheet that will offer developers a reminder of recommended practices done in REST API Development.
Accept and respond with JSON
JSON is the standard for transferring data. Almost every networked technology can use it: JavaScript has built-in methods to encode and decode JSON either through the Fetch API or another HTTP client. Server-side technologies have libraries that can decode JSON without doing much work. |
To make sure that when our REST API app responds with JSON that clients interpret it as such, we should set Content-Type
in the response header to application/json
after the request is made. Many server-side app frameworks set the response header automatically. Some HTTP clients look at the Content-Type response header and parse the data according to that format. |
NOTE: Spring Boot offers great support for responding with json or xml format, without effort.
Use nouns instead of verbs in the endpoint path
Nouns represent the entity that we are trying to recover or manipulate in pathname. Verbs should be avoided because they are already present, they are the HTTP requests types: GET
, POST
, DELETE
, PUT
, etc. |
Adding verbs in API pathname doesn't add more value, it makes the pathname even more longer and doesn't help in the description of the API. |
Good examples:
[GET] /api/books
[GET] /api/book
[POST] /api/book
Bad examples:
[GET] /api/getAllBooks
[GET] /api/getBook
Using plural in resources naming
We should name collections with the plural form of the nouns, because it's very common when you want to recover a list of resources to also want to recover one resource from that list and vice versa. |
We use the plural form to be consistent with what is in your database. A table has more than one entity/record and we as developers should name our endpoint in such a way to reflect this, or more formally to be consistent. |
Example(s):
/api/book/{id}
and /api/books
/api/account/{id}
and /api/accounts
/api/person/{id}
and /api/persons
|
|
Versioning the API
We should always version our API's as good practice. Versioning is something that clients appreciate and offers them more trust when using your API, because you will not enforce modification on their side for each major implementation update on your API, but instead they are going to migrate to your new version only when they are ready. |
Example:
https://appgateway.lidlplus.com/app/v19/RO/tickets/list/
where v19 shows the version number.
Allow filtering, sorting & pagination
A database behind a REST API can be very big and that means that it's not always a good idea to return everything to the client, because it may slow down the system. In these cases we must offer the client some filtering options based on what he specifically wants.
Filtering and also pagination grows the performance of your REST API because it doesn't make the system to compile the entire database of resources in the response. |
Example:
http://example.com/articles/?sort=+author,-datepublished
Where +
means ascending.
Where -
means descending.
A response body should never contain HTTP info
We should avoid completely putting HTTP information into the response body. |
We don't need to tell the caller of the API in the response body that the API worked with 200 OK or 404 NOT FOUND (etc.). |
Our API should be capable in case of error to fail with an HTTP correct status. And not offer confusing information in the response body like failing with 200 OK |
Example of bad response
{
"status" : "200",
"response: "OK",
"id" : 1,
"name" : Stefan
"age" : 25
}
Use and maintain good security practices
Use SSL/TLS for security.
Introducing a SSL certificate on a server is not difficult, actually presents a really low cost and there is no reason not to make our API that can be called publicly (even private) secured. |
|
Created By
Metadata
Comments
No comments yet. Add yours below!
Add a Comment
Related Cheat Sheets