Auth, validation, one error format and rate limiting for a new endpoint.
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 /itemshas 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.