Agent skill
api-design
Design RESTful APIs following conventions with proper error handling, versioning, and documentation. Use when creating or modifying API endpoints.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/api-design-junior-frontend-dev-hi-u-ng
SKILL.md
API Design Skill
Purpose
Create consistent, well-designed APIs.
REST Conventions
Reference: standards/rest-conventions.md
HTTP Methods
| Method | Use Case | Idempotent |
|---|---|---|
| GET | Retrieve resource | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | No |
| DELETE | Remove resource | Yes |
URL Patterns
GET /users # List users
GET /users/:id # Get user
POST /users # Create user
PUT /users/:id # Replace user
PATCH /users/:id # Update user
DELETE /users/:id # Delete user
GET /users/:id/posts # Nested resource
Response Status Codes
| Code | Meaning | Use When |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation error |
| 401 | Unauthorized | Auth required |
| 403 | Forbidden | Auth insufficient |
| 404 | Not Found | Resource doesn't exist |
| 422 | Unprocessable | Business rule violation |
| 500 | Server Error | Unexpected error |
Error Response Format
Reference: standards/error-responses.md
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Versioning
Reference: standards/versioning.md
Options:
- URL:
/api/v1/users - Header:
Accept: application/vnd.api.v1+json
Recommendation: URL versioning for simplicity
Endpoint Documentation
Use template: templates/endpoint-doc.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
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.
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.
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.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
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?