moai-ref-api-patterns

Use plural nouns in lowercase kebab-case for resources, such as /api/v1/user-profiles. Map CRUD operations to HTTP methods: POST creates, GET reads, PUT replaces, PATCH partially updates, and DELETE removes. Keep nested resources to a maximum of two levels deep.

Return 200 for successful reads and updates, 201 for resource creation, and 204 for deletions without a body. Use 400 for validation failures, 401 for missing authentication, 403 for insufficient authorization, 404 for missing resources, 409 for conflicts, and 429 for rate limiting.

Return a JSON object with a machine-readable error code, a human-readable message, field-level details array, and a request_id for traceability. Never expose stack traces in production, and use generic messages like "Invalid email or password" for login failures.

Use offset pagination with page and limit parameters for typical datasets where total counts matter. Use cursor-based pagination for large datasets where offset performance degrades, returning an opaque next cursor and a has_more flag instead of page numbers.

Breaking changes require a version bump: removing or renaming fields, changing field types, removing endpoints, or changing authentication methods. Adding optional fields, new endpoints, or new query parameters are non-breaking and need no version change.

It does not cover frontend development, DevOps, database schema design, or security audits. It focuses specifically on API design conventions, error handling, and input validation for backend endpoint implementation and review.