e41ecfad4c
Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>
67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# API Template
|
|
|
|
REST / DTO / validation / versioning / error standards for service APIs.
|
|
|
|
Short contract form: [templates/api-template.md](../templates/api-template.md).
|
|
|
|
## REST Standards
|
|
|
|
| Rule | Detail |
|
|
| --- | --- |
|
|
| Prefix | `/api/v1` for public service APIs |
|
|
| Resources | Nouns; plural collections (`/programs`, `/leads`) |
|
|
| Methods | GET read · POST create/actions · PATCH/PUT update · DELETE remove/archive as designed |
|
|
| Auth | JWT (and documented internal tokens); deps in `api/deps.py` |
|
|
| Tenant | `X-Tenant-ID` (and documented alternatives); reject when missing on tenant routes |
|
|
| Pagination | Shared page meta pattern |
|
|
| Thin routers | Validate → authorize → service call → map response |
|
|
|
|
Health endpoints may live at `/health` (and `/capabilities` when applicable) outside `/api/v1`.
|
|
|
|
## DTO Rules
|
|
|
|
1. Pydantic schemas in `app/schemas/` — `Create`, `Update`, `Read`, `List` suffixes.
|
|
2. Never expose password hashes, provider secrets, or internal tokens.
|
|
3. Do not return ORM models directly from routers.
|
|
4. External refs are explicit fields (`crm_contact_ref`, etc.).
|
|
5. Document breaking field changes in phase handover.
|
|
|
|
## Validation Rules
|
|
|
|
1. Request body/query validated by Pydantic.
|
|
2. Domain rules enforced in services/validators — not only at the edge.
|
|
3. `tenant_id` in body does not override resolved tenant context.
|
|
4. Path IDs are UUIDs/strings as per service; always combined with tenant scope server-side.
|
|
|
|
## Versioning
|
|
|
|
1. Current public version: `v1`.
|
|
2. Additive changes preferred within `v1`.
|
|
3. Breaking changes require a new version path (`/api/v2`) or a documented migration window in the phase.
|
|
4. Deprecated fields remain until the compatibility gate allows removal.
|
|
|
|
## Error Responses
|
|
|
|
1. Use shared exception types / stable `error_code` values.
|
|
2. Map to appropriate HTTP status: 400 validation · 401 auth · 403 forbidden · 404 not found · 409 conflict · 422 domain · 429 rate limit · 500 unexpected.
|
|
3. Do not leak stack traces or secrets in production payloads.
|
|
4. Document new error codes in the phase API section.
|
|
|
|
## Endpoint Documentation Block
|
|
|
|
```markdown
|
|
| Method | Path | Description | Auth / Permission |
|
|
| --- | --- | --- | --- |
|
|
| POST | /api/v1/example | Create example | JWT + `service.example.create` |
|
|
```
|
|
|
|
Also update [api-reference.md](../reference/api-reference.md) / [services-contracts.md](../reference/services-contracts.md) when the phase publishes stable contracts.
|
|
|
|
## Related Documents
|
|
|
|
- [Authorization Architecture](../architecture/authorization-architecture.md)
|
|
- [Security Architecture](../architecture/security-architecture.md)
|
|
- [Service Layer Template](service-layer-template.md)
|
|
- [Coding Standards](../development/coding-standards.md)
|
|
- [templates/api-template.md](../templates/api-template.md)
|