REST versioning

REST version less (content-negotiation)

Using Accept header (you could also use custom headers but Accept header seems better because it already exists in the HTTP protocol. The Accept header is used for choosing the Content-Type.

• Proxy X-Device-Accept:

When forwarding an HTTP request with altered HTTP header fields, in addition to complying with the rules of normal HTTP operation, proxies must include in the request additional fields of the form "X-Device-". In our case Accept header becomes X-Device-Accept.

• Proxy caches, Vary header:

It must be used the Vary header in order to avoid proxy caches (header changed and proxy does not realize if we do not use the Vary header) When having same URL but different Accept header request, proxies will not return the previously cached URL. What means, proxy will keep track of URL and Accept header to find out whether it is a new request that was not previously cached. The Vary header must be used for request and response (I think)

• Github:

Example Github: Accept: application/vnd.github.v3+json

• Advantages:
1. Clients do not need to update their links.
2. Other services linking to our own ones will never be broken because the link is always the same.
3. URL must be some resource. If throught different versions the resource returns more, less or different data the URL must not be changed as long as the resource is the same. REST philosophy.
• Disadvantages:
1. Headers and JSONP.
2. Developers can not just use a web browser because API requires headers. They must use other tools like curl commands.

REST URL versioning

• Advantages:
1. JSONP
2. Developers can use a web browser for accessing to our REST API.
• Disadvantages:
1. Clients, server and other services linking to our own ones must update their links (what at the end is the same as non versioning URL)
2. Other services linking to our own ones require to update their links.
3. It does not follow the REST philosophy. Just ONE URL for ONE resource.

REST message based (Service Stack)

Data versioning.

• ServiceStack RESTfull resource versioning - ServiceStack RESTfull resource versioning.
• Advantages of message based web services - Advantages of message based web services

References

Your API versioning is wrong.

Three ways of doing the same, pick up whatever suits you but version less is the REST way.

Enterprise REST.

URL versioning VS Accept header. If you version your URL you must update client, server and other services linking to your own one. What at the end is the same as non versioning.

How to version REST URIs.

It must always be used the Accept header.

Best practices for API versioning.

Using version less and versioning at the same time.

Proxies and original headers.

What headers are modified by proxies when forwarding.

The Accept header.

The Accept header.

Roy T. Fielding: versioning.

Roy T. Fielding says: do not version your resources if they are not totally different. Same resource, same URL ALWAYS.

Roy T. Fielding: APIs must be hypertext driven.

Roy T. Fielding about what really is an API REST (really difficult to achieve)

Public REST APIs: examples.

Github, VMware, django framework and many others support the Accept header. What means, they are not versioning URLs.

Postel's law.

Be conservative in what you do, be liberal in what you accept from others.

Get Lucky!!!