API Design Specification Template

URL path versioning (`/v1/resource`) is simpler for consumers to understand and easier to test in a browser or curl. Header-based versioning (`Accept: application/vnd.api+json; version=2`) is cleaner in URL design but harder to debug. For most product APIs with fewer than 1,000 consumers, URL path versioning is the practical choice. The [API-First Design glossary entry](/glossary/api-first-design) covers how versioning fits into the broader API design philosophy.

Use REST when your consumers need simple CRUD operations on well-defined resources, when caching matters (REST uses HTTP caching natively), or when most consumers are external partners. Use [GraphQL](/glossary/graphql) when consumers need flexible queries across deeply nested relationships, when mobile bandwidth is a constraint (clients fetch exactly what they need), or when your internal frontend team is the primary consumer.

Detailed enough for the consumer to fix the problem without contacting support. Include a machine-readable code (for programmatic handling), a human-readable message (for debugging), field-level details (for form validation), and a documentation URL. Never expose internal stack traces or database errors in production responses.

Include `total_count` only if your database can compute it efficiently. For large tables, `COUNT(*)` can be expensive. If you include it, document that the count may be approximate for large datasets. Always include `has_more` so consumers know whether to paginate, regardless of whether you include a total count.

Use API keys for server-to-server integrations where a specific user context is not needed. Use OAuth 2.0 with user tokens when the API call needs to act on behalf of a specific user. Document both flows clearly and ensure [rate limits](/glossary/rate-limiting) differ by auth type, since server-to-server integrations typically need higher throughput. ---