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 transferring 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 technologies have libraries that can decode JSON some filtering options based on what he specifically wants.
without doing much work. Filtering and also pagination grows the performance 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 Content-Typein the database of resources in the response.
response header to application/json
after the request is Example:
made. Many server-side app frameworks set the response header http://example.com/articles/?sort=+a‐
automatically. Some HTTP clients look at the Content-Type response uthor,-datepublished
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 descending.
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 information 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 information in the response
pathname even more longer and doesn't help in the description of body like failing with 200 OK
the API.
Example of bad response
Good examples: {
[GET] /api/books "status" : "200",
[GET] /api/book "response: "OK",
[POST] /api/book "id" : 1,
"name" : Stefan
Bad examples: "age" : 25
[GET] /api/getAllBooks }
[GET] /api/getBook
Use and maintain good security practices
Using plural in resources naming
Use SSL/TLS for security.
We should name collections with the plural form of the nouns, Introducing a SSL certificate 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/record and we as
developers should name our endpoint in such a way to reflect this, or
more formally to be consistent.
Example(s):
and /api/books
/api/book/{id}
and /api/accounts
/api/account/{id}
and /api/persons
/api/person/{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 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.
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
