Skip to main content

REST techniques

Content-negotiation#

Request Header#

Accept: application/vnd.github.v3+json

Response Header#

content-type: application/json; charset=utf-8


Caching#

ETag Header#

ETag: โ€œ33a64df551425fcc55e4d42a148795d9f25f89d4โ€

Caching Unchanged Resources#

GET request includes the ETag in the header

If-None-Match: โ€œ33a64df551425fcc55e4d42a148795d9f25f89d4โ€

The server sends back a 304 Not Modified status, without a body, which tells the client that the cached version of the response is still good to use (fresh).

Collision avoidance:#

POST request includes the ETag in the header

If-Match: โ€œ33a64df551425fcc55e4d42a148795d9f25f89d4โ€

The server sends back 412 Precondition Failed status if the resource changed between the client read and write.


API Versioning#

Through Content negotiation#

Accept: application/vnd.github.v3+json

Version in the path#

https://api.bank.com/v1/accounts


Pagination#

Specify page and per_page query params

https://api.github.com/users/octocat/repos?page=1&per_page=5


Non-CRUD/Functional API#

Specify the function using action query param

POST /accounts/1234?action=deactivate


Complex queries#

Specify options like sort field, order, etc. as query params

/customers?sort=worth&order=desc&offset=1&limit=100


Projections#

Specify the fields to be included in the response using query params /customers?fields=id,name,age


Hypermedia#

Every response can contain links to related reources and actions

{
"links": [
{
"rel": ["self"],
"href": "/customers/1234"
}
]
}