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

API Template

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

Short contract form: templates/api-template.md.
Enterprise default: mandatory-phase-artifacts.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).

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

| 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