REST Endpoint Template¶
Copy this template into docs/api/rest/<endpoint-or-feature>.md (or a sub-file per endpoint) whenever you add or change a REST endpoint. Document every endpoint you own; keep response shapes stable (see ../api/rest/README.md).
# <Verb> /<version>/<path> — <Title>
## Overview
What this endpoint does and who calls it (which client/version).
## Attributes
| Field | Value |
| ------------ | ----------------------------------------------- |
| Method | `GET` / `POST` / `PUT` / `PATCH` / `DELETE` |
| Path | `/v2/…` |
| Auth | `Bearer <access>` / `authorize(['SUBSCRIBER'])` |
| Content-Type | `application/json` |
## Request
### Path / query parameters
| Param | Type | Required | Description |
| ----- | ---- | -------- | ----------- |
### Body
```json
{}
```
Response¶
200 OK¶
Errors¶
| Status | Code | When |
|---|---|---|
| 401 | Unauthorized | missing/invalid token |
| 403 | Forbidden | role not allowed |
| 422 | Unprocessable Entity | validation failure |
Notes¶
- Validation schema (Fastify + zod) reference.
- Idempotency, pagination, caching, rate-limit behaviour.
- Any backward-compatibility notes.
Related Documents¶
- ../templates/rest-api.md
- ../development/validation.md
- ../development/authentication.md
- ../development/error-handling.md
---
## Rules
- Use deterministic ordering and steady pagination for lists (see
[../database/optimization.md](../database/optimization.md)).
- Keep existing response shapes / field names / status codes stable.
- Do not document internal errors; hide stack traces.
## Checklist
- [ ] Schema validation documented
- [ ] Auth + authz documented
- [ ] All success + error codes listed
- [ ] Example request/response included
- [ ] Relative links resolve