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

1xx

2xx

  • 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.

3xx

  • 304 – `Not modified` – The resource was not modified since last time
  • 4xx – Some client errors

    5xx – Some server errors (in the code)

    Caching

    Last-Modified

    Two headers used in request and response

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

    ETag

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

    Pagination

    • 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,address.zip`. 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`

    Sorting

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

    Error response format

    ???

    Versioning

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

    Notes

    • 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.