# REST API Design

> Use when: design RESTful HTTP APIs with correct resources, methods, status codes, and pagination.

- Skill: `kimtth/rest-api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kimtth/rest-api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimtth/rest-api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: kimtth (https://skillmd.com/u/kimtth)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimtth/rest-api-design

---


Goal: HTTP APIs that follow REST conventions consumers expect.

Use for:
- designing resource-oriented HTTP endpoints
- reviewing method, status code, and URL choices
- adding pagination, filtering, and idempotency

Workflow:
1. Model nouns as resources; use HTTP methods for verbs.
2. Use GET (safe), POST (create), PUT/PATCH (update), DELETE.
3. Return correct status codes: 2xx, 4xx for client, 5xx for server.
4. Make PUT and DELETE idempotent; guard POST with idempotency keys.
5. Paginate collections; support filtering and sorting via query params.
6. Document the contract and version breaking changes.

Conventions:
- plural resource nouns: /users, /users/{id}/orders
- 201 + Location on create, 204 on empty success
- consistent error body with code and message
- cursor or page-based pagination, documented

Rules:
- methods match semantics; GET must not mutate
- choose status codes by meaning, not habit
- keep endpoints resource-oriented, not RPC-in-disguise
- never break URLs or shapes without versioning