rest-best-practices

# REST Best Practices (Deep Workflow) REST is **HTTP semantics** used consistently: **resources** as nouns, **methods** with meaning, **predictable** errors, and **cacheable** reads where safe. ## When to Offer This Workflow **Trigger conditions:** - Designing public or partner HTTP APIs - Inconsistent verbs (GET with side effects); wrong status codes - CDN/caching surprises; client retry storms on POST **Initial offer:** Use **six stages**: (1) resource model, (2) methods & safety, (3) status & errors, (4) pagination & filtering, (5) caching & conditional requests, (6) versioning & evolution). Confirm JSON conventions and authentication model. --- ## Stage 1: Resource Model **Goal:** Clear collection vs item resources; relationships via sub-paths or hypermedia links (HATEOAS optional). **Exit condition:** Table or diagram of resources, identifiers, and canonical URLs. --- ## Stage 2: Methods & Safety **Goal:** GET/HEAD safe and idempotent; POST for creation or non-idempotent actions; PUT replaces; PATCH partial; DELETE removes. ### Anti-patterns - Non-idempotent GET; overloaded POST for everything without documented patterns --- ## Stage 3: Status & Errors **Goal:** Correct 4xx vs 5xx; consistent error body (e.g., RFC 7807 Problem Details) with stable `type` codes and optional `instance` for support. --- ## Stage 4: Pagination & Filtering **Goal:** Cursor pagination for large lists; document sort/filter query params; cap page sizes. --- ## Stage 5: Caching & Conditional Requests **Goal:** ETag/Last-Modified for cacheable GET; Cache-Control directives; validate with intermediaries (CDN) when used. --- ## Stage 6: Versioning & Evolution **Goal:** URL prefix or header versioning; deprecation policy; **Idempotency-Key** on POST when clients retry. --- ## Final Review Checklist - [ ] Resource model clear and consistent - [ ] HTTP methods match semantics; GET is safe - [ ] Status codes and errors consistent - [ ] Pagination and filtering documented - [ ] Caching headers where appropriate - [ ] Versioning and idempotency strategy ## Tips for Effective Guidance - Not everything is CRUD—model commands as sub-resources or task resources explicitly. - Pair with **openapi-spec** for contract-first workflows. ## Handling Deviations - Internal APIs still benefit from the same discipline—future consumers are often external.