TorbatYar/docs/ai-framework/api-template.md

API Template

REST / DTO / validation / versioning / error standards for service APIs.

Short contract form: 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

| Method | Path | Description | Auth / Permission |
| --- | --- | --- | --- |
| POST | /api/v1/example | Create example | JWT + `service.example.create` |

Also update api-reference.md / services-contracts.md when the phase publishes stable contracts.

Related Documents

• Authorization Architecture
• Security Architecture
• Service Layer Template
• Coding Standards
• templates/api-template.md