REST-API

Guidelines

General

  1. REST-APIs MUST be stateless

  2. REST-APIs MUST be at least maturity level 2,

    i.e., URIs point to resources and proper HTTP verbs are used.

  3. GET requests MUST NOT change any resource

  4. ULID SHOULD be used

    when generating random unique identifiers for resources to combine the advantages of UUIDs with those of autoincremented primary keys (especially performance through sortability).

  5. Resources MUST be plural names except if it is a single resource.

    For example, /users/ for all users and /users/1234 for a single user with ID 1234 but the resource avatar is singular in /users/1234/avatar since a user has exactly one avatar.

  6. Resources MUST NOT be verbs

  7. URIs MUST be in lower kebab case

    This means especially that underscores MUST NOT be used in URIs to avoid problems when the URI underlined.

  8. Parameters and fields MUST be in lower camel case

    following the Google JSON Style Guide

  9. GET requests SHOULD NOT contain payload

    This is recommended by Mozilla.

  10. The query parameter fields MAY be used with GET requests to only retrieve certain fields.

    For example, the hypothetical GET request /users?fields=lastName,age returns only the last name and age of all users.

Errors

  1. 404 SHOULD be used instead of 401

    if a 401 would disclose to an unauthorized party that the resource exists

  2. If a URL points at an existing resource, all parent URLs MUST NOT return a 404.

    For example, if /users/1234 returns a 200, then /users/ must exist and cannot return 404. If it cannot be accessed by anyone, 403 should be returned or, if the user could access it by logging in, 401.

  3. Endpoints MUST respond with appropriate HTTP status codes.

  4. Errors MUST NOT be conveyed using a 2xx HTTP status codes.

  5. Errors MUST be reported using application/problem+json.

Filtering and Pagination

  1. Big collections MUST be paginated and SHOULD be filterable

  2. Filtering SHOULD follow the JSON:API

  3. Pagination SHOULD use cursors instead of offsets if able

    (e.g. cursor based pagination does not work with sorting)

  4. If pagination returns no elements (possible for offset-based pagination if the offset is too large), a 204 MUST be returned.

  5. If the pagination parameters a malformed, a 400 MUST be returned.

    This is the case for example if the cursor points to a resource that does not exist or the user does not have access to it or if the limit is less than or equal to 0.

  6. PUT requests MUST update the entire resource.

    Especially if a resource is a collection, PUT MUST set the entire colleciton.

  7. To update only part of a resource, PATCH SHOULD be used (RFC 5789).

  8. To update (parts of) a resource, JSON Patch (RFC 6902) MAY be used.

    For example, the following HTTP request will rename the user with ID 1234 to newname:

    PATCH /users/1234 HTTP/2
Host: http://example.org/
Accept: */*
Content-Type: application/json-patch+json

[
    { "op": "replace", "path": "username", "value": "newname"}
]