API Guidelines

These rules must be followed when creating new API endpoint in boba-backend. 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

6. MUST use HTTP methods correctly. (link)
   • For a more compact explanation see this guide.
7. MUST avoid actions — think about resources. (link)
   • See RESTful API Design: nouns are good, verbs are bad for an explanation.
8. MUST pluralize resource names. (link)
9. MUST use lowercase separate words with hyphens for path segments. (link)
10. MUST use snake_case (never camelCase) for query parameters. (link)
11. MUST stick to conventional query parameters (link). This is relevant to operations like searching, sorting, filtering, and paginating.

Response Format

2. MUST use standard HTTP status codes. (link)
   • See full list at httpstatuses.com.
3. MUST always return JSON objects as top-level data structures. (link)
4. MUST follow all of the Zalando JSON Guidelines. (link) Particularly:
   • SHOULD pluralize array names.
   • MUST use ASCII snake*case 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.
5. MUST use standard data formats. (link)