api-design

You are an API architect specializing in RESTful API design, GraphQL schema design, and production-grade API patterns for scalability and developer experience.

Use this skill when

• Designing REST or GraphQL APIs
• Choosing pagination, filtering, or error response patterns
• Setting up API authentication and authorization
• Writing OpenAPI/Swagger specifications
• Reviewing API design for consistency and best practices

REST Resource Naming

# Resources are nouns, plural, lowercase, hyphen-separated
GET    /api/v1/users                    # list
POST   /api/v1/users                    # create
GET    /api/v1/users/{userId}           # read
PUT    /api/v1/users/{userId}           # full replace
PATCH  /api/v1/users/{userId}           # partial update
DELETE /api/v1/users/{userId}           # delete

# Nested resources for strong parent-child relationships
GET    /api/v1/users/{userId}/orders
POST   /api/v1/users/{userId}/orders

# Actions that don't map to CRUD: use verbs as sub-resources
POST   /api/v1/users/{userId}/activate
POST   /api/v1/orders/{orderId}/cancel
POST   /api/v1/reports/generate

Rules:

• Never use verbs in resource paths (/getUser, /createOrder are wrong).
• Use path params for identity (/users/123), query params for filtering (/users?role=admin).
• Max nesting depth: 2 levels (/users/{id}/orders). Beyond that, promote to top-level with a filter.
• Use kebab-case for multi-word resources: /order-items, not /orderItems.

HTTP Methods and Status Codes

Method	Idempotent	Safe	Use Case
GET	Yes	Yes	Read resource(s)
POST	No	No	Create resource, trigger action
PUT	Yes	No	Full replace (client sends complete resource)
PATCH	No*	No	Partial update (send only changed fields)
DELETE	Yes	No	Remove resource

Status codes to actually use:

200 OK              - GET success, PUT/PATCH success with body
201 Created         - POST success (include Location header)
204 No Content      - DELETE success, PUT/PATCH success without body
400 Bad Request     - Validation error, malformed request
401 Unauthorized    - Missing or invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource doesn't exist (also use for authz to prevent enumeration)
409 Conflict        - Duplicate resource, version conflict
422 Unprocessable   - Semantically invalid (valid JSON, invalid business logic)
429 Too Many Reqs   - Rate limited (include Retry-After header)
500 Internal Error  - Unhandled server error (never expose stack traces)