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.