API Design Standards

API Design Standards

Endpoint Naming

• use nouns and plural resources
• use /api/v3/<resource>

Request/Response

• JSON in/out
• success: status/data/meta
• error: status/errors/meta
• list/document collection endpoints must accept updated_from and updated_to filters
• detail-by-id endpoints do not require updated range filters

Validation and Errors

• validate before service/repository execution
• return HTTP status aligned with error class (400/401/404/422/500)

Pagination

• request: page, per_page
• response: meta.pagination

Versioning

• path-based major versioning (/api/v3)