REST API Versioning (With Examples)

Author:

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

One way to version a REST API is to include the version number in the URI path.
Examples:

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

In this approach, we create a completely different URI for the new service.

http://www.example.com/api/v1/products

http://www.example.com/api/v2/products

Real-world examples:



2. Versioning through query parameters

Another option for versioning a REST API is to include the version number as a query parameter.

Examples:

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

Real-world examples:

3. Versioning through custom headers

REST APIs can also be versioned by providing custom headers with the version number included as an attribute. The main difference between this approach and the two previous ones is that it doesn’t clutter the URI with versioning information.

Examples:

http://localhost:8080/api/products

headers=[X-API-VERSION=1]

http://localhost:8080/api/products

headers=[X-API-VERSION=2]

Pros: It doesn’t clutter the URI with versioning information

Cons: It requires custom headers

4. Versioning through content negotiation

The last strategy we are addressing is versioning through content negotiation.

In this approach, we use the Accept header in the request.

Examples:

http://localhost:8080/api/products

headers[Accept=application/vnd.javaguides-v1+json]

http://localhost:8080/api/products

headers[Accept=application/vnd.javaguides-v2+json]

Real-world examples:

Related Articles

Free Spring Boot Tutorial | Full In-depth Course | Learn Spring Boot in 10 Hours

Watch this course on YouTube at Spring Boot Tutorial | Fee 10 Hours Full Course