Agent skill
api-design-patterns
RESTful API design patterns including URL structure, HTTP methods, and idempotency. Use when designing new API endpoints or reviewing API architecture. For existing projects, follow the project's established conventions instead.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/api-design-patterns-cooldaemon-dotfiles
SKILL.md
API Design Patterns
Core Principle
For new projects, enforce RESTful URL structure. For existing projects, follow the project's established API conventions.
RESTful URL Structure
GET /api/resources # List resources
GET /api/resources/:id # Get single resource
POST /api/resources # Create (server assigns ID)
PUT /api/resources/:id # Create or replace at specific ID
PATCH /api/resources/:id # Partial update
DELETE /api/resources/:id # Delete resource
# Query parameters for filtering, sorting, pagination
GET /api/resources?status=active&sort=created_at&limit=20&offset=0
HTTP Methods and Idempotency
| Method | Idempotent | Use Case |
|---|---|---|
| GET | Yes | Retrieve resource(s) |
| PUT | Yes | Create or replace at specific URI |
| PATCH | No* | Partial update |
| DELETE | Yes | Remove resource |
| POST | No | Non-idempotent operations |
PUT vs POST
Common misconception: "POST = create, PUT = update" Reality: PUT can create, POST can do various things. The difference is idempotency.
- PUT: Client specifies the ID. Idempotent (running twice = same result)
- POST: Server assigns the ID. Non-idempotent (running twice = two resources)
Anti-Patterns
| Anti-Pattern | Correct Approach |
|---|---|
Verbs in URLs (/getUser/123) |
Use HTTP methods (GET /users/123) |
| Ignoring idempotency | PUT for idempotent creates, POST for non-idempotent |
| Inconsistent pluralization | Always use plural nouns (/users, not /user) |
Deeply nested resources (/a/1/b/2/c/3) |
Flatten beyond 2 levels |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?