Skip to main content

REST API Guidelines

Route Design​

  • APIs MUST be resource-oriented (nouns over verbs).
  • Base prefix SHOULD be /api.
  • HTTP methods MUST preserve semantics:
    • GET read
    • POST create
    • PUT replace
    • PATCH partial update
    • DELETE remove

Route Conventions​

Recommended pattern:

  • GET /api/<resources>
  • POST /api/<resources>
  • GET /api/<resources>/:id
  • PATCH /api/<resources>/:id
  • DELETE /api/<resources>/:id

Legacy action routes MAY remain for compatibility but SHOULD be phased out.

Request/Response Contracts​

  • DTOs MUST be defined in schemas/.
  • Handlers MUST parse into typed structs, not generic maps.
  • Response shape SHOULD stay consistent within a domain.
  • Error shape SHOULD include stable status/code/message fields.

Status Codes​

  • 200 successful read/update
  • 201 successful create
  • 204 successful delete with no body
  • 400 malformed request or validation failure
  • 401 unauthenticated
  • 403 unauthorized
  • 404 not found
  • 409 conflict
  • 410 deprecated/removed endpoint
  • 429 rate/quota limited
  • 500 unhandled server error

Validation​

Validation MUST happen in three layers:

  1. transport parsing (body, path, query)
  2. schema validation (required/range/enum)
  3. business validation in service/model layer

IDs and UUIDs MUST be validated before DB calls.

Pagination​

Collection endpoints SHOULD support page and pageSize.

Recommended contract:

  • defaults: page=1, bounded pageSize
  • response: items, total, page, pageSize, totalPages

Versioning​

Breaking API changes MUST use explicit versioning (/api/v1, /api/v2).