Rest Best Practices

Deep REST workflow—resource modeling, HTTP methods and safety, status codes, errors, pagination, caching, versioning, and idempotency. Use when designing HTTP APIs or reviewing controllers and gateways.

mike47512@mike47512

Install

openclaw skills install @mike47512/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.