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.