---
name: api-design
description: "Production HTTP API design — REST conventions, pagination, error models, versioning, rate limiting, auth, and idempotency. Use when designing or reviewing public/internal HTTP APIs, OpenAPI contracts, pagination, error models, rate limits, auth, or idempotent write endpoints."
---
# API Design

## Reference guide

Read only the references needed for the current request:

- **REST Conventions That Actually Matter**: [references/rest-conventions-that-actually-matter.md](references/rest-conventions-that-actually-matter.md)
- **Pagination: Cursor vs Offset**: [references/pagination-cursor-vs-offset.md](references/pagination-cursor-vs-offset.md)
- **Error Handling: RFC 9457 Problem Details**: [references/error-handling-rfc-9457-problem-details.md](references/error-handling-rfc-9457-problem-details.md)
- **API Versioning**: [references/api-versioning.md](references/api-versioning.md)
- **Rate Limiting**: [references/rate-limiting.md](references/rate-limiting.md)
- **Authentication Patterns**: [references/authentication-patterns.md](references/authentication-patterns.md)
- **Idempotency**: [references/idempotency.md](references/idempotency.md)
- **OpenAPI 3.1 Specification**: [references/openapi-3-1-specification.md](references/openapi-3-1-specification.md)
- **GraphQL vs REST: Decision Matrix**: [references/graphql-vs-rest-decision-matrix.md](references/graphql-vs-rest-decision-matrix.md)
- **Response Envelope**: [references/response-envelope.md](references/response-envelope.md)
- **Checklist: Production-Ready API**: [references/checklist-production-ready-api.md](references/checklist-production-ready-api.md)