5c6a2e78cf
Register all active platform services and base features in core DB so admin can manage them, add delivery/hospitality/sports-center backend phases, update apps catalog and production deploy tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# API Template
|
|
|
|
REST / DTO / validation / versioning / error / OpenAPI standards for service APIs.
|
|
|
|
Short contract form: [templates/api-template.md](../templates/api-template.md).
|
|
Enterprise default: [mandatory-phase-artifacts.md](mandatory-phase-artifacts.md) · [definition-of-done.md](definition-of-done.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 — **required** on collection list endpoints |
|
|
| Filtering | Query params for common attributes — **required** when lists are filterable |
|
|
| Sorting | Stable sort keys documented — **required** on collection lists |
|
|
| Searching | Text/search params when users must find by name/code/etc. |
|
|
| Thin routers | Validate → authorize → command/query/service call → map response |
|
|
|
|
## Operational & Capability Surfaces
|
|
|
|
| Endpoint | Purpose | Required |
|
|
| --- | --- | --- |
|
|
| `GET /health` | Liveness / basic readiness signal | Every runnable service |
|
|
| `GET /capabilities` | Feature/channel/bundle discovery | Platform / discoverable services |
|
|
| `GET /metrics` | Operational metrics | Prefer yes; else justified N/A |
|
|
| Permission routes / registry | List or document `{service}.*` tree | Privileged services |
|
|
|
|
## OpenAPI Documentation
|
|
|
|
1. FastAPI-generated OpenAPI must include all new/changed public routes before Complete.
|
|
2. Operation summaries, response models, and error shapes should be accurate.
|
|
3. Export or link OpenAPI in service README / reference docs when contracts stabilize.
|
|
4. Undocumented public routes fail the API Completeness gate ([quality-gates.md](quality-gates.md)).
|
|
|
|
## 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.
|
|
6. List responses include page metadata (items + total/page/size or cursor as per service pattern).
|
|
|
|
## Validation Rules
|
|
|
|
1. Request body/query validated by Pydantic.
|
|
2. Domain rules enforced in services/validators/policies/specs — 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)
|