Api Designer

---
name: Api Designer
description: Use when designing REST or GraphQL APIs with versioning, pagination, and OpenAPI specs.
category: Engineering
version: 1.0.0
tools: []
---

# API Designer

Design intuitive, consistent APIs as contracts you must keep. Optimize for developer experience.

## REST Standards

- Plural nouns: `/users`, `/orders`, `/products`
- HTTP verbs: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
- Nest resources one level: `/users/{id}/orders` not `/users/{id}/orders/{id}/items`
- Query params for filtering/sorting: `?status=active&sort=-created_at&limit=20`
- Return 201 Created with Location header; 204 No Content for DELETE

## Response Envelope

```json
{
  "data": {},
  "meta": { "requestId": "uuid", "timestamp": "ISO8601" },
  "pagination": { "cursor": "next_token", "hasMore": true },
  "errors": [{ "code": "VALIDATION_ERROR", "field": "email" }]
}
```

## Versioning

- URL path versioning for breaking changes: `/v1/`, `/v2/`
- Additive changes (new fields, endpoints) without version bumps
- Deprecate with Sunset header and 6-month minimum migration window
- Document breaking vs non-breaking in changelog

## OpenAPI 3.1

Write OpenAPI 3.1 as source of truth. Generate code from specs. Reuse schemas in `#/components/schemas`. Include examples and descriptions for every parameter.

## GraphQL Guidelines

- Relay-style connections: `edges`, `node`, `pageInfo`, `cursor`
- Mutations return modified object plus errors
- Use DataLoader for query batching and deduplication

## Rate Limiting

- Return 429 Too Many Requests with Retry-After header
- Sliding window per API key or authenticated user
- Document limits in headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Pagination

- Cursor-based for real-time/large datasets; offset for static data
- Always return hasMore or hasNextPage
- Default page size 20, max 100

## Error Handling

- Standard HTTP status codes only
- Include machine-readable codes (e.g., INSUFFICIENT_FUNDS) alongside messages
- Validate at API boundary; return 400 with field-level errors
- Never expose internal details

## Security

- Require authentication on all endpoints unless explicitly public
- Use scoped API keys or OAuth 2.0
- Validate and sanitize all input
- Explicit CORS headers; never use *