API versioning is the practice of transparently managing changes to your API.
We will look at 4 ways of versioning a REST API.
1. Versioning through URI Path
2. Versioning through query parameters
3. Versioning through custom headers
4. Versioning through content negotiation
Learn REST basics at https://www.javaguides.net/p/restful-tutorial.html
When to version REST API
One of the major challenges surrounding exposing services is handling updates to the API contract. Clients may not want to update their applications when the API changes, so a versioning strategy becomes crucial. A versioning strategy allows clients to continue using the existing REST API and migrate their applications to the newer API when they are ready.
APIs only need to be up-versioned when a breaking change is made. Breaking changes include:
- Changing the request/response format (e.g. from XML to JSON)
- Changing a property 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 (e.g. removing description from a product)
4 REST API Versioning Strategies
1. Versioning through URI Path
- http://www.example.com/api/1/products
- http://www.example.com/api/v1/products
- http://www.example.com/api/v2/products
- http://www.example.com/api/v1/posts
- http://www.example.com/api/v1/employees
- http://www.example.com/api/v1/products
- http://www.example.com/api/v2/products
2. Versioning through query parameters
- http://www.example.com/api/products?version=1
- http://www.example.com/api/products?version=2
- http://www.example.com/api/posts?version=1
- http://www.example.com/api/employees?version=1
3. Versioning through custom headers
4. Versioning through content negotiation
Related Articles
- Overview of REST
- REST API - HTTP Methods // Popular
- REST API - HTTP Status Codes // Popular
- Advantages of REST
- REST API - REST Architectural Constraints // Popular
- REST API - REST Architectural Properties
- REST API - REST Architectural Elements
- Difference Between SOAP vs REST Web Services
- How to Identify REST Resources
- How to Design URL to REST Resource // Popular
- How to Assign HTTP methods to REST Resources
- How to Model JSON Representation Format // Popular
- What HTTP Status Code to Return
Comments
Post a Comment
Leave Comment