What is API Versioning?
"API versioning is the practice of transparently managing changes to your API." Just like any other software, APIs have versions. When a lot of customers depend on an API's endpoints and services, one change could break a lot of software across the web. How do software engineers negotiate versioning?
API Contracts
Similar to legal contracts, API contracts govern interactions between the downstream service (consumer) and the upstream service (provider) and list all the methods with which a consumer can interact with the provider. A "breaking change" is a change in these contracts, such as:
- Changing the request/response format (e.g. from XML to JSON)
- Changing a property or API parameter name (e.g. from name to productName) or data type on a property (e.g. from an integer to a float)
- Adding a required field on the request (e.g. a new required header or property in a request body)
- Removing a property on the response or the API payload (e.g. removing description from a product)
These changes "break" the contract and force API users to change their code to interact with the API. Of course, software developers need to improve their APIs, and users need to keep using them. This is where clear communication and versioning can help.
How should I Version an API?
There are different methods of versioning an API:
- URI (Uniform Resource Identifier) versioning. This means changing what the API is called in a request- for example, `http://myapi.example.com` becomes `http://myapiv2.example.com`
- Versioning using Custom Request Header. This reads the version of the incoming call with a query parameter and delivers that version of the API.
- Versioning using Accept header. This adds a custom header to requests that looks like `Accept: version=1.0`, to specify what version of the API is being requested.
Conclusion
API versioning is ideally guided by API management core principles. Always following engineering best practices, but also communicate clearly with your customers so versioning goes smoothly for everyone.
