general

API as a Contract

An API is a contract with its consumers, not a thin wrapper over the database schema. Design every endpoint from the consumer's point of view, then map it onto the internal model — never the other way around. Hold the contract to five pillars:

• Consistency — the same concept is named, shaped, and paginated the same way across every endpoint (field casing, date format, error envelope, pagination shape).
• Predictability — identical inputs produce identical, documented outputs; no hidden side effects, no surprise defaults.
• Discoverability — resources, relationships, and allowed actions are reachable from naming conventions and links, not tribal knowledge.
• Stability — published request/response shapes do not change under consumers; breaking changes go through versioning, never a silent payload edit.
• Security by default — endpoints are authenticated, authorized, validated, and rate-limited unless an explicit, documented reason makes one public.

Do not leak internal database structure across the contract: column names, surrogate keys, join tables, enum integers, and storage-only fields stay behind a DTO / API Resource. The response exposes what the consumer needs, named for the consumer.

Resource-Oriented REST

Endpoints represent resources (nouns), not actions (verbs). The HTTP method carries the action.

• Use /users, /users/{id}, /users/{id}/orders — never /getUser, /createUser, /users/{id}/delete, /doPayment.
• Use plural collection nouns; nest sub-resources under their parent (/users/{id}/orders).
• The rare genuine non-CRUD operation that cannot be modeled as a resource state change is the only exception, and it is named as a clearly-scoped sub-resource action (POST /orders/{id}/refunds), not a verb dangling off the root.

Correct HTTP Methods & Idempotence

Pick the method by its contract, and honor its idempotence guarantee:

• GET — read-only, safe, idempotent, cacheable. Never mutates state, never carries a request body that changes the outcome.
• POST — creates a subordinate resource or triggers a non-idempotent operation. Repeating it may create duplicates (see Idempotency Keys).
• PUT — full replacement of a resource at a known URI; idempotent (repeating yields the same end state).
• PATCH — partial update; should be idempotent for a given payload.
• DELETE — removes the resource; idempotent (a second delete returns the same terminal state, typically 404 or 204, not a new error).