Api design

Skill edjchapman/claude-code-config/skills/api-design

REST API conventions — resources, status codes, pagination, error shapes. Use when designing or reviewing routes, controllers, endpoints, serializers, or schemas.From its SKILL.md

Install

npx -y skills add edjchapman/claude-code-config --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.5 KB, as published. Nobody here has run it

API Design Standards

Apply these conventions when building or reviewing REST APIs.

URL Structure

Use nouns, not verbs: /users not /getUsers
Plural resource names: /users, /orders, /products
Nested resources for clear ownership: /users/{id}/orders
Maximum 2 levels of nesting; beyond that, use query parameters
Use kebab-case: /user-profiles not /userProfiles

HTTP Methods

Method	Purpose	Idempotent	Response
GET	Read resource(s)	Yes	200 with data
POST	Create resource	No	201 with created resource
PUT	Full replace	Yes	200 with updated resource
PATCH	Partial update	Yes	200 with updated resource
DELETE	Remove resource	Yes	204 no content

Status Codes

Use the correct status code for the situation:

Success

200 OK -- successful GET, PUT, PATCH
201 Created -- successful POST that creates a resource
204 No Content -- successful DELETE

Client Errors

400 Bad Request -- validation failure, malformed input
401 Unauthorized -- missing or invalid authentication
403 Forbidden -- authenticated but lacking permission
404 Not Found -- resource doesn't exist
409 Conflict -- duplicate resource, state conflict
422 Unprocessable Entity -- valid syntax but semantic errors
429 Too Many Requests -- rate limit exceeded

Server Errors

500 Internal Server Error -- unexpected server failure
503 Service Unavailable -- temporary overload or maintenance

Error Response Format

Use a consistent error structure across all endpoints:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid fields.",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address."
      }
    ]
  }
}

Always include a machine-readable code
Include human-readable message
Use details array for field-level validation errors
Never expose stack traces or internal details in production

Pagination

Use cursor-based or offset-based pagination for list endpoints:

{
  "data": [...],
  "pagination": {
    "next_cursor": "abc123",
    "has_more": true,
    "total_count": 142
  }
}

Default page size: 20, max: 100
Include total_count when practical (skip for expensive counts)
Use cursor param for cursor-based, page/limit for offset-based

Filtering and Sorting

Filter with query params: GET /users?status=active&role=admin
Sort with sort param: GET /users?sort=-created_at (prefix - for descending)
Search with q or search param: GET /users?q=john

Versioning

Use URL path versioning: /api/v1/users
Only increment major version for breaking changes
Support previous version for a documented deprecation period

Response Envelope

Wrap responses consistently:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Rate Limiting

Return 429 Too Many Requests when limit exceeded
Include headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Apply per-user or per-API-key, not per-IP alone