ReddRadar
Agent skill
api-design
RESTful API design principles, patterns, and best practices. Use when building backend APIs. (project)
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/design/api-design-hydershah-advance-appliance
SKILL.md
API Design Principles
REST Conventions
HTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Retrieve resource(s) | Yes |
| POST | Create new resource | No |
| PUT | Replace entire resource | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove resource | Yes |
URL Structure
GET /api/v1/users # List all users
GET /api/v1/users/:id # Get single user
POST /api/v1/users # Create user
PUT /api/v1/users/:id # Replace user
PATCH /api/v1/users/:id # Update user
DELETE /api/v1/users/:id # Delete user
# Nested resources
GET /api/v1/users/:id/posts # User's posts
Response Format
Success Response
{
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 100
}
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
}
HTTP Status Codes
Success (2xx)
200 OK- Successful GET, PUT, PATCH201 Created- Successful POST204 No Content- Successful DELETE
Client Errors (4xx)
400 Bad Request- Invalid input401 Unauthorized- Authentication required403 Forbidden- Permission denied404 Not Found- Resource doesn't exist409 Conflict- Resource conflict422 Unprocessable Entity- Validation failed
Server Errors (5xx)
500 Internal Server Error- Unexpected error503 Service Unavailable- Temporary unavailable
Pagination
Offset-based
GET /api/v1/users?page=2&limit=20
Cursor-based
GET /api/v1/users?cursor=abc123&limit=20
Filtering & Sorting
GET /api/v1/users?status=active&role=admin
GET /api/v1/users?sort=-created_at,name
GET /api/v1/users?fields=id,name,email
Authentication
JWT Token
Authorization: Bearer <token>
API Key
X-API-Key: <api-key>
Versioning
URL Path (Recommended)
/api/v1/users
/api/v2/users
Header
Accept: application/vnd.api+json; version=1
Rate Limiting Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
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?