I've notice in some example two ways of versioning an api.
One of them is using a version in the url
/api/v1/products
The other is using the content type header and the accept header to mark the api version for the data send to the server
Content-Type=application/vnd.company.v2+xml
What are the pros and cons to this approaches ? What are some use case where you will use each approach ?
URI Path. The most common way to version an API is in the URI path. This method employs URI routing to direct requests to a specific version of the API.
The drawback to using URL versioning is that by changing the URL of a resource with each new API version we are violating the REST constraint that each resource be accessible via a unique URL.
API versioning is the practice of transparently managing changes to your API. Managing an API boils down to defining and evolving data contracts and dealing with breaking changes. The most effective way to evolve your API without breaking changes is to follow effective API change management principles.
Both mechanisms are valid. You need to know your consumer to know which path to follow. In general, working with enterprises and academically-minded folks tends to point developers towards Resource Header versioning. However, if your clients are smaller businesses, the URL versioning approach is more widely used.
Here are the Pros and Cons that I could find (I'm sure there are more, and some of the Cons have work arounds not mentioned here)
It's more explorable. For most requests you can just use a browser, whereas, the Resource Header implementation requires a more programatic approach to testing. However, because not all HTTP requests are explorable, for example, POST requests, you should use a Rest Client plugin like Postman or Paw. URI Pro/Header Con
With a URI-versioned API, resource identification and the resource’s representation is munged together. This violates the basic principles of REST; one resource should be identified by one and only one endpoint. In this regard, the Resource Header versioning choice is more academically idealistic. Header Pro/URI Con.
Here are some helpful links if you want to do some further reading:
I've been used to having the version number in the URL itself (/v1/). I personally think this is a much cleaner approach - this way, the end user (or developer) doesn't need to handle HTTP headers, and can simply modify the REST API/call to access different versions of the API as needed.
I'm thinking that its also possible that some of the HTTP APIs out there in different languages may not have full support for HTTP headers, so you always make to make the API most readily available to the end user. Re-writing the URL is the simplest way, and it should work with anything that supports HTTP out there.
Finally, allowing the API version to be specified using the URL allows simple testing using a web browser. If you incorporate versioning into a HTTP header, the developer is forced to use a programming language to do testing.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With