Situation:
Evolving a REST API is a difficult problem – one for which many options are available - Solution for API Versioning.
Action:
> Specifying the version number in URI E.g.: /v2/products/
The URI in REST should represent the resource only
This is not suggested unless the entire set of APIs migrate to a new platform
> Passing the version number as a URI Parameter: E.g.: /products?version=2
• This is used by Amazon, Google and Netflix
• Parameters are used for filtering resources and should not specify the implementation
• The APIs have to parse the param string before knowing where to route the request.
> Using the well-known HTTP header: The Accept header is used to make up our own resource types. E.g.:
Accept: application/vnd.test.v2 + json
This means that I, as a vendor, can define (and can register) a media
type. If we do this it's called a 'vendor' media type. It works and
well-known.
The disadvantage with this approach is it is not very intuitive.
According to the Rest API specifications, A REST API should be entered with no prior knowledge beyond the initial
URI (bookmark) and set of standardized media types that are appropriate
for the intended audience. Failure here implies that out-of-band
information is driving interaction instead of hypertext.
So URIs are not part of the contract!
A REST API should spend almost all of its descriptive effort in defining
the media type(s) used for representing resources and driving
application state, or in defining extended relation names and/or
hypertext-enabled mark-up for existing standard media types.
So the Media Type definitions are part of the contract and should be prior knowledge for the client that consumes the API.
Conclusion:
This article tried to provide an overview of the very diverse and difficult problem of
evolving a REST Service.
We discussed the two common solutions, advantages and disadvantages of
each one, and ways to reason about these approaches in the context of
REST. The article concludes by making the case for the second solution –
versioning the media types, while examining the possible changes to a RESTful API.Finally Considering all the above, using well-known HTTP header, Accept may be a better option.
@RequestMapping(..., produces = "application/vnd.company.app-[1.0-1.6]+json)
@ResponseBody
public Object method1() {
// so something
return object;
}
@RequestMapping(..., produces = "application/vnd.company.app-[1.7-]+json)
@ResponseBody
public Object method2() {
// so something
return object;
}
