Gsd-skill-creator api-design

Name: api-design
Author: Tibsfox

REST API design best practices. Use when designing APIs, choosing status codes, or creating endpoints.

install

source · Clone the upstream repo

git clone https://github.com/Tibsfox/gsd-skill-creator

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Tibsfox/gsd-skill-creator "$T" && mkdir -p ~/.claude/skills && cp -r "$T/examples/skills/patterns/api-design" ~/.claude/skills/tibsfox-gsd-skill-creator-api-design && rm -rf "$T"

manifest: examples/skills/patterns/api-design/SKILL.md

source content

REST API Design

Endpoint Rules

Nouns, not verbs:
```
/users
```
not
```
/getUsers
```
— HTTP method is the verb
Plural nouns:
```
/users
```
,
```
/orders
```
— consistent collections
Kebab-case:
```
/user-profiles
```
not
```
/user_profiles
```
Max 2 levels nesting:
```
/users/{id}/orders
```
— deeper use query params
No trailing slashes, no extensions

HTTP Methods

Method	Purpose	Idempotent
GET	Retrieve	Yes
POST	Create	No
PUT	Replace entire resource	Yes
PATCH	Partial update	No
DELETE	Remove	Yes

Status Codes

Code	Use When
200	Success with body
201	Resource created (+ Location header)
204	Success, no body (DELETE)
400	Malformed request
401	Not authenticated
403	Authenticated but forbidden
404	Not found
409	Conflict (duplicate)
422	Valid syntax, invalid semantics
429	Rate limited

Error Format

{"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [], "request_id": "req_..."}}

Key Rules

Always paginate lists (cursor-based preferred, max page size enforced)
Never expose sequential IDs — use UUIDs
Auth credentials in headers, never URLs
Return 400 for unknown parameters (catch typos)
Include request_id in every response