REST API design parts

Endpoint API actions

http://api/v1/pets http://api/v1/pets/8765
GET List of all pets Get one pet
POST Create a new pet
PUT Replace entire collection Replace or create a pet
DELETE Delete all pets Delete one pet

API endpoints parameters

  • Path. Example: `/messages/123`
  • Query. Example: `?query=something` or `?categories=cars,helicopters`
  • Body. For non-GET requests. Payloads JSON or XML formatted
  • Request Header. For example `Origin`

Status codes



  • 201 – `Created` and also need to put `Location` header into response with link to newly created entity
  • 202 – `Accepted` – need to process, the response is not ready yet.
  • 204 – `No Content` – if nothing to put into response
  • 206 – `Partial content` – When not all content is not returned. For example for pagination purposes. `Link` header is preferable to add links to other endpoints in order to get other parts.


  • 304 – `Not modified` – The resource was not modified since last time

4xx – Some client errors

5xx – Some server errors (in the code)



Two headers used in request and response

  • Request header `Modified-Since`
  • Response header `Last-Modified`


  • Request header `If-None-Match`
  • Response header `ETag`


  • with page number `?page=2&page-size=25`
  • with cursor `?cursor=293082` – to continue with “next” entity in the list
  • with accept range header: `Accept-Ranges`, `Content-Range`, `Range`

Rate limitation

These headers returns in response:

  • `X-RateLimit-Limit: 100` – What is actual limit
  • `X-RateLimit-Remaining: 74` – How many requests remaining
  • `X-RateLimit-Reset: 12343432432` – When the limit will be reset (timestamp)

Output filtering

  • Specify needed fields `?fields=firstname,lastname,`. Note that there is sub-resource address defined
  • Specify excluded fields `?exclude=biography,age`
  • Specify style `?style=compact` or `?style=full`
  • Request header `Prefer: return=compact`, Response `Preference-Applied: return=compact`


  • SQL style: `?sort=title+DESC,author+ASC`

Error response format



  • in the URL ``
  • In request header: `X-API-Version: 2`
  • In Accept header: `Accept: application/vnd.restaurants.v2+json`


  • Never use verbs as entity in URLs. Only nouns allowed as entity names. Verbs good to represent some action on an entity: `/message/13/vote`
  • Good to wrapping collection with additional entity in response `{ entity: { … } }`.
  • Better to use plural forms of entity names in URLs: `/tickets/123` is better than `/ticket/123`
  • Better to use lowercased names (with underscores or dashes)
  • Always be consistent with naming whatever style is chosen.
  • Id must be UIDs instead of incremental ids. For example: “lwkr23j3i” instead of 1, 2, 3
  • Use sub-entities only if these entities cannot be used on itsown. `/tickets/123/messages/23` should be possible only if `messages` cannot be used itself separately.

Books to read

Comments are closed.