← Todos os modelos

Autenticação, validação, um único formato de erro e limite de pedidos para um endpoint novo.

Spec — REST endpoint with auth

Status: draft · Created: 2026-10-12

1. Context and goal

A resource is exposed over HTTP to signed-in clients, with consistent validation, errors and rate limits.

2. Functional requirements (EARS)

  • FR-1: WHEN a request has no valid bearer token, THE SYSTEM SHALL answer 401 with the error format of FR-6.
  • FR-2: WHEN the token is valid but lacks the scope of the route, THE SYSTEM SHALL answer 403.
  • FR-3: WHEN GET /items/{id} names an item the caller may read, THE SYSTEM SHALL answer 200 with the item.
  • FR-4: IF the item does not exist or the caller may not read it, THEN THE SYSTEM SHALL answer 404 without telling the two cases apart.
  • FR-5: WHEN POST /items has a body that fails validation, THE SYSTEM SHALL answer 422 naming every invalid field.
  • FR-6: THE SYSTEM SHALL answer every error as { "code", "message" } with a stable code.
  • FR-7: WHILE a client exceeds 60 requests a minute, THE SYSTEM SHALL answer 429 with Retry-After.
  • FR-8: THE SYSTEM SHALL record each write with the caller and the time.

3. Out of scope

  • Pagination and filters of the list route.