Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

REST API Versioning - Is There a Right Answer?

DZone's Guide to

REST API Versioning - Is There a Right Answer?

Got some questions about REST API versioning? Here's a look at whether versioning is necessary, a response data change example, and a version-free URI example.

· Integration Zone
Free Resource

Modernize your application architectures with microservices and APIs with best practices from this free virtual summit series. Brought to you in partnership with CA Technologies.

I noted in a recent post, Processing in a RESTful World, one of the biggest debates within RESTful API design centers around performing actions via a RESTful call into your API. An equally discussed area within RESTful API design focuses on versioning for the endpoints deployed.

Is Versioning Needed?

Image title

A common train of thought puts forward the idea to not version your API unless it is absolutely necessary. If your development team has created a RESTful API to serve an internal client, you probably do not need to worry about versioning your API. Taking things a step further, if you maintain control over all the clients that access your API, the same may be true.

However, in the case where you have a public API or an API where you do not control every client using the RESTful API, versioning of your API may be required as business needs evolve.

Example - Change In Response Data

To illustrate, let's assume the following end-point exists:

http://myhost/tasks

The original version of the /tasks URI returns the following data:

[
{
"id" : "101",
"name" : "Test Task #1",
"status" : "Pending Approval"
},
{
"id" : "102",
"name" : "Test Task #2",
"status" : "Approved"
}
]

After some review of the design, updates were required which caused the data to be modified as shown below:

[
{
"id" : "101",
"name" : "Test Task #1",
"statusHistory" : [
{
"statusDate" : "2015-12-01 11:27:00",
"status" : "New"
},
{
"statusDate" : "2015-12-02 14:05:00",
"status" : "Pending Approval"
}
]
},
{
"id" : "102",
"name" : "Test Task #2",
"statusHistory" : [
{
"statusDate" : "2015-12-01 07:14:00",
"status" : "New"
},
{
"statusDate" : "2015-12-05 09:17:00",
"status" : "Pending Approval"
},
{
"statusDate" : "2015-12-07 10:17:00",
"status" : "Approved"
}
]
}
]

In the example above, the status field was moved into a collection of child objects. The core issue with this change is that users of the /tasks URI no longer have access to the "status" field/value. As a result, customers who were relying on this information may experience issues as a result of this change. If the customers are all controlled by the owner of the API, this change could be coordinated, but that is not the case with all RESTful APIs.

Two Very Common Approaches

There are two common approaches designed to handle versioning with APIs. The first is to include the version in the URI and is used by Google, Twitter and Salesforce:

https://cloud.google.com/translate/v2/using_rest
https://api.twitter.com/1.1/statuses/user_timeline.json
https://na1.salesforce.com/services/data/v20.0/

The second is to reference the version as a query parameter. Below, are some examples in use by Ebay and Netflix:

http://open.api.ebay.com/shopping?version=713
http://api.netflix.com/catalog/titles/series/70023522?v=1.5

Developers must include the version they wish to use, when accessing services provided in the examples above. As a result, when newer versions are released, it is up to the caller of the service to determine if/when they wish to upgrade. The only consequence to this approach is that developers must be cognizant of the end-of-life for the version they are using. As an example, version 20.0 is quite old within Salesforce, with the current version being 35.0.

The Version-Free URI

Some API developers have provided a version-free URI, which always references most recent version of the end-point. In the example above, following the twitter example, the following URI's might be available:

http://myhost/v1/tasks - the original data is returned, with status field/value
http://myhost/v2/tasks - removes status field/value, introduces statusHistory child collection
http://myhost/tasks - version-free, returns the same as v2 URI below

In this scenario, developers have the option to use the version-free /tasks URI or they can reference a given version. However, the use of the version-free URI could result in issues. In our example, if the client were expecting the status field/value, the update to v2 would cause issues, since it has been removed.

Critics of RESTful API Versioning

There are some opinions associated with versioning within a RESTful API.

1. RESTful end-points provide access to resources.

The thought behind the criticism is that requesting the resource should not contain a version, as doing so ties the representation of the resource to the resource identification. My only challenge to this criticism is with the example I provided above, where the task object changed between version 1 and version 2. In this case, there is a difference between task at version 1 (includes status field/value) and version 2 (no longer includes status).

2. Versioning end-points that did not change.

The challenge with this criticism is that for a given release cycle, there may be no changes for some end-points. In the example provided, there were changes to the task resource, but what if that was the only change? By design, all the other end-points would have a corresponding version 2.0 - even though nothing changed. Leaving all the other end-points at version 1.0, though, would generate a great deal of confusion for customers of the API.

Conclusion

The idea of versioning with a RESTful API is certainly far from reaching a universal standard. For an example, take a look at the following thread on Stack Overflow:

Stack Overflow - Best Practices for API Versioning

My only recommendation is to avoid using versioning with your RESTful API, unless you do not have a choice. If you find yourself required to version your API, I would determine which approach best meets the needs of your development team and customers.

Have a really great day!

The Integration Zone is proudly sponsored by CA Technologies. Learn from expert microservices and API presentations at the Modernizing Application Architectures Virtual Summit Series.

Topics:
integeration ,java ,rest ,rest api ,versioning

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}