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