Rest Api Design

A solid reference for REST API conventions that covers the essentials: resource naming with plural nouns, proper HTTP method usage, status code selection, and response formatting. Shows good versus bad URL patterns, includes a clean table of when to use 200 versus 201 versus 204, and demonstrates pagination and filtering with query parameters. The JSON-API inspired response format with data, meta, and links is opinionated but clean. Use this when you're designing a new API from scratch or trying to get your team aligned on consistent conventions. It won't make architectural decisions for you, but it will keep you from reinventing basic patterns or mixing POST and GET semantics.

skills.sh installs: 600
GitHub stars: 248
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add secondsky/claude-skills --skill rest-api-design --agent claude-code

Installs into .claude/skills of the current project.

Files

REST API Design

Design RESTful APIs with proper conventions and developer experience.

Resource Naming

# Good - nouns, plural, hierarchical
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/users
PATCH  /api/users/123
DELETE /api/users/123

# Bad - verbs, actions in URL
GET    /api/getUsers
POST   /api/createUser
POST   /api/users/123/delete

HTTP Methods

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

Status Codes

Code	Meaning	Use For
200	OK	Successful GET, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Validation errors
401	Unauthorized	Missing auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limited