atelier/domains/api/rest.md

REST — Derived Rules

Derives from domains/api/first-principles.md. Applies P1–P10 to REST specifically.

Resource Naming (P2 Clarity, P3 Predictability)

• Nouns, not verbs: /users, /orders, not /getUsers.
• Plural: /users (collection), /users/{id} (item).
• Lowercase, hyphenated: /order-items, not /OrderItems or /order_items.
• Nesting max 2 levels: /users/{id}/orders, not /users/{id}/orders/{oid}/items/{iid}.

HTTP Methods (P1 Contract Fidelity, P6 Idempotency)

Method	Semantics	Idempotent	Safe
GET	Read	Yes	Yes
POST	Create	No	No
PUT	Replace (full)	Yes	No
PATCH	Update (partial)	No	No
DELETE	Remove	Yes	No

• PUT requires the full resource. PATCH requires only the delta. Never accept a partial PUT.
• POST creates; never use POST for read operations. POST is not cacheable.

Status Codes (P9 Error Transparency, P1 Contract Fidelity)

Code	Meaning	When
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST that created a resource
204	No Content	Successful DELETE, or empty response
400	Bad Request	Malformed request (client error)
401	Unauthorized	Authentication required or failed
403	Forbidden	Authenticated but not permitted
404	Not Found	Resource does not exist
409	Conflict	State conflict (e.g., duplicate)
422	Unprocessable	Well-formed but semantically invalid
429	Too Many Requests	Rate limited
500	Internal Error	Server bug — never leak stack trace

• Never return 200 on an error. Never return 500 with a stack trace.
• 401 vs 403: 401 = "who are you?", 403 = "I know who you are, but you can't."

Idempotency (P6 Idempotency)

• POST: not idempotent. Use an idempotency key (Idempotency-Key header) for safe retry.
• PUT: idempotent by definition — same PUT twice = same state.
• DELETE: idempotent — deleting a non-existent resource is success (204).
• PATCH: not idempotent by default; can be made idempotent with explicit versioning.

Pagination (P7 Performance, see pagination.md)

• Default to cursor pagination for collections > 100 items.
• Never return unbounded collections.
• Link header or cursor field in response body.

Versioning (P5 Versioning, P10 Stability, see versioning.md)

• Version in the URL (/v1/users) or in the header (Accept: application/vnd.atelier.v1+json).
• Pick one. Be consistent across all endpoints.
• Never make a breaking change without a new version and a deprecation cycle.

Security (P8 Security, see domains/security/)

• HTTPS only. Redirect HTTP to HTTPS.
• Authentication on every non-public endpoint. No opt-in auth.
• Rate limiting on write endpoints (POST, PUT, PATCH, DELETE).
• Validate every input against a schema. Never pass raw request body to the database.