Skip to main content

API guidelines

These rules must be followed when creating new API endpoint in BobaServer. They're a subset of the excellent Zalando RESTful API guidelines.

The Golden Rule

  1. MUST document every endpoint using the OpenAPI format (see How to Write Documentation).

Request Format

  1. MUST use HTTP methods correctly. (link)
  2. MUST avoid actions โ€” think about resources. (link)
  3. MUST pluralize resource names. (link)
  4. MUST use lowercase separate words with hyphens for path segments. (link)
  5. MUST use snake_case (never camelCase) for query parameters. (link)
  6. MUST stick to conventional query parameters (link). This is relevant to operations like searching, sorting, filtering, and paginating.

Response Format

  1. MUST use standard HTTP status codes. (link)
  2. MUST always return JSON objects as top-level data structures. (link)
  3. MUST follow all of the Zalando JSON Guidelines. (link) Particularly:
    • SHOULD pluralize array names.
    • MUST use ASCII snakecase for property names (and never camelCase): `^[a-z][a-z_0-9]*$`.
    • SHOULD not use null for empty arrays.
    • MUST not use null for boolean properties.
    • SHOULD name date/time properties with _at suffix.
    • MUST use same semantics for null and absent properties.
  4. MUST use standard data formats. (link)