API documentation
OpenAPI (Swagger) specification
Industry-standard format for describing RESTful APIs. Benefits include:
- Interactive documentation: Swagger UI for testing APIs in browser
- Code generation: Auto-generate client SDKs and server stubs
- API validation: Validate requests/responses against schema
- Contract-first development: Design API spec before implementation
Documentation best practices
Comprehensive documentation
- Clear operation descriptions explaining what each endpoint does
- Request/response examples for every operation
- Error codes and their meanings
- Authentication and authorization requirements
- Rate limiting policies and quotas
- Deprecation notices and migration guides
- Code samples in multiple languages
- Getting started guide and tutorials
API versioning
Manage API evolution without breaking existing clients. Common strategies:
Versions over time
202520262027
v1
v2
v3
PreviewGenerally availableDeprecated
Client traffic per version
v1
100%
v2
0%
v3
0%
v1 is the only stable version; v2 is in preview with early adopters.
GET /v1/customers/1042
HTTP/1.1 200 OK
Content-Type: application/json
Illustrative example
URI versioning
Version in URL path: /v1/customers, /v2/customers
Pros: Simple, explicit, easy to route
Header versioning
Version in custom header: X-API-Version: 2 or Accept: application/vnd.company.v2+json
Pros: Clean URIs, supports content negotiation
Query parameter versioning
Version in query string: /customers?version=2
Pros: Easy to implement, default version support
Versioning best practices
- Version only when breaking changes are necessary
- Support at least N-1 versions (current and previous)
- Communicate deprecation timelines clearly
- Use semantic versioning (major.minor.patch) internally
- Expose major version only in public API