Common Practices for REST API Development Cheat Sheet

by Paladuta Stefan via cheatography.com/139860/cs/30803/

Accept and respond with JSON Allow filtering, sorting & pagination

JSON is the standard for transf​erring data. Almost every networked A database behind a REST API can be very big and that means that
technology can use it: JavaScript has built-in methods to encode and it's not always a good idea to return everything to the client, because
decode JSON either through the Fetch API or another HTTP client. it may slow down the system. In these cases we must offer the client
Server​-side techno​logies have libraries that can decode JSON some filtering options based on what he specif​​ically wants.
without doing much work. Filtering and also pagination grows the perfor​​mance of your REST
To make sure that when our REST API app responds with JSON that API because it doesn't make the system to compile the entire
clients interpret it as such, we should set Conten​t-Typein the database of resources in the response.

response header to applic​ati​on/json

after the request is Example:
made. Many server​-side app frameworks set the response header http:/​/ex​amp​le.c​om​/ar​tic​les​/?s​ort​=+a​‐
automa​tic​ally. Some HTTP clients look at the Conten​t-Type response uth​or,​-da​tep​ubl​ished
header and parse the data according to that format. Where + means ascending.
NOTE: Spring Boot offers great support for responding with json or Where - means descen​ding.
xml format, without effort.
A response body should never contain HTTP info
Use nouns instead of verbs in the endpoint path We should avoid completely putting HTTP inform​​ation into the
Nouns represent the entity that we are trying to recover or response body.
manipulate in pathname. Verbs should be avoided because they are We don't need to tell the caller of the API in the response body that
already present, they are the HTTP requests types: GET, the API worked with 200 OK or 404 NOT FOUND (etc.).
POST,DELETE, PUT, etc. Our API should be capable in case of error to fail with an HTTP
Adding verbs in API pathname doesn't add more value, it makes the correct status. And not offer confusing inform​​ation in the response
pathname even more longer and doesn't help in the descri​​ption of body like failing with 200 OK
the API.
Example of bad response
Good examples: {
[GET] /api/books ​ ​ ​"​sta​tus​" : "​200​",
[GET] /api/book ​ ​ ​"​res​ponse: "​OK",
[POST] /api/book ​ ​ ​"​id" : 1,
​ ​ ​"​nam​e" : Stefan
Bad examples: ​ ​ ​"​age​" : 25
[GET] /api/g​etA​llBooks }
[GET] /api/g​etBook
Use and maintain good security practices
Using plural in resources naming
Use SSL/TLS for security.
We should name collec​​tions with the plural form of the nouns, Introd​​ucing a SSL certif​​icate on a server is not difficult, actually
because it's very common when you want to recover a list of presents a really low cost and there is no reason not to make our API
resources to also want to recover one resource from that list and vice that can be called publicly (even private) secured.
versa.
We use the plural form to be consistent with what is in your
database. A table has more than one entity​​/r​ecord and we as
developers should name our endpoint in such a way to reflect this, or
more formally to be consis​​tent.

Exampl​e(s):
and /api/books
/api/b​ook​/{id}
and /api/a​ccounts
/api/a​cco​unt​/{id}
and /api/p​ersons
/api/p​ers​on/{id}

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 modifi​cation on their
side for each major implem​​en​t​ation update on your API, but instead
they are going to migrate to your new version only when they are
ready.

Example:
https:​//a​ppg​ate​way.li​dlp​lus.co​m/a​pp/​‐
v19​/RO​/ti​cke​ts/​list/ where v19 shows the version
number.

By Paladuta Stefan Published 2nd November, 2022. Sponsored by Readable.com

cheatography.com/paladuta- Last updated 2nd November, 2022. Measure your website readability!
stefan/ Page 1 of 2. https://readable.com