# 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)