API Versioning and Documentation Standard

BCCAbout 3 min

API Versioning and Documentation Standard

This document details our API versioning strategy

1. Overview

Effective API versioning is essential for:

Backward Compatibility: Ensuring that existing clients are not disrupted by new changes.
Clear Communication: Signaling the impact of changes through version numbers.
Clean Endpoints: Maintaining uncluttered URLs by removing version information from the resource path.
Consistent Documentation: Using OpenAPI to provide clear, version-specific documentation for all API endpoints.

Our strategy relies exclusively on HTTP headers for versioning, while OpenAPI serves as our standard for documentation.

2. Versioning via HTTP Headers

2.1. When to version?

Over-Versioning: Creating a new version for every small change leads to confusion and fragmentation.
Unclear Deprecation Policies: Removing or changing endpoints without proper notice can break client integrations.
Inconsistent Versioning Schemes: Mixing versioning methods (e.g., URI-based vs. header-based) within the same API undermines clarity.
Insufficient Documentation: Failing to communicate differences between versions and migration paths leaves developers in the dark.

2.2. The `X-API-Version` Header

We have standardized on using the X-API-Version header to indicate the API version a client wishes to consume. This method offers several advantages:

Simplicity: Clients specify the version number directly in the HTTP header.
Consistency: The API endpoint URL remains static and clean.
Flexibility: The versioning mechanism is decoupled from the URL, making it easier to evolve the API without changing endpoint patterns.

Example Request:

GET /resource HTTP/1.1
Host: api.example.com
X-API-Version: 2

3. Versioning Strategy

3.1. Semantic Versioning Principles

We adhere to semantic versioning, which helps to communicate the nature of changes:

Major Versions (v1, v2, …): Introduce breaking changes.
Minor Versions: Add backward-compatible features.
Patch Versions: Include backward-compatible bug fixes.

Since only Major versions would introduce breaking changes, only the major version is required on the X-API-Version header. eg. X-API-Version: 2

The full semantic version eg. 2.1.4 should be used versioning the published sdks as well as affected routes in the open api documentation, for example to state the a new route is available since 2.1

3.2. Backward Compatibility

Non-breaking Enhancements: Add new features without altering existing endpoints.
Deprecation Policy: Provide clear, advanced notice for deprecated features and offer migration guides to help developers transition smoothly.

In OpenAPI v3, you can mark an endpoint as deprecated using the deprecated keyword. This signals to clients that the endpoint should not be used anymore.

Example:

paths:
/old-endpoint:
get:
summary: Deprecated endpoint
description: This endpoint is deprecated. Please use /new-endpoint instead.
deprecated: true
responses:
"200":
description: Successful response

4. Implementation Details

4.1. Header Parsing

Have your service check each incoming HTTP request for the X-API-Version header. If the header is missing, the latest version is assumed. This mechanism allows us to:

Route requests to the appropriate API version.
Maintain backward compatibility while supporting newer versions concurrently.

4.2. Documentation and Developer Support

OpenAPI Standard for Documentation https://editor.swagger.io/

Unified Documentation: We maintain our API documentation using the OpenAPI standard, which guarantees that our documentation is both comprehensive and automatically generated.
Version-Specific Specs: Each API version has its own OpenAPI specification, ensuring that developers have access to accurate details, including endpoints, parameters, response formats, and error codes.
Interactive Docs: OpenAPI enables interactive documentation, making it easier for developers to explore the API, test endpoints, and generate client SDKs.
Changelogs and Migration Guides: Detailed changelogs and migration guides accompany each version, helping developers understand the differences between versions and plan upgrades accordingly.

5. Advantages of Header-Based Versioning with OpenAPI Documentation

Uncluttered URLs: Endpoints remain consistent and free from embedded version numbers.
Decoupled Versioning: Separating the versioning mechanism from resource identification simplifies API design and evolution.
Accurate Documentation: Using OpenAPI ensures that documentation is always in sync with the API implementation, providing clarity and reducing errors.
Ease of Evolution: New versions can be deployed without altering the core URL structure, minimizing integration issues while ensuring that developers can reference the correct documentation for their API version.

6. Conclusion

By standardizing on the X-API-Version header for versioning and leveraging the OpenAPI standard for documentation, we ensure a scalable and developer-friendly approach that:

Simplifies client configuration.
Maintains a clean and consistent URL structure.
Facilitates smooth transitions between API versions through clear documentation and robust deprecation policies.
Provides interactive, version-specific documentation that evolves alongside our API.

This strategy, inspired by industry best practices, positions our API services for long-term stability and ease of evolution while empowering developers with the tools and documentation they need.