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.

Safety Notice

This listing is from the official public ClawHub registry. Review SKILL.md and referenced scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "rest-best-practices" with this command: npx skills add 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.

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open Registry RecordOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Coding

Spicy Ai Video

Turn a 60-second talking head clip into 1080p high-energy edited videos just by typing what you need. Whether it's turning bland footage into visually intens...

Registry SourceRecently Updated
100tk8544-b
Coding

Video Maker Fast

Get polished MP4 videos ready to post, without touching a single slider. Upload your video clips (MP4, MOV, AVI, WebM, up to 500MB), say something like "trim...

Registry SourceRecently Updated
120peand-rover
Coding

Generation Generator

generate text prompts or clips into AI generated videos with this skill. Works with MP4, MOV, PNG, JPG files up to 500MB. marketers, content creators, social...

Registry SourceRecently Updated
80mory128
Coding

Editor On Android

Get edited MP4 clips ready to post, without touching a single slider. Upload your video clips (MP4, MOV, AVI, WebM, up to 500MB), say something like "trim th...

Registry SourceRecently Updated
160mory128