I am planning to write a RESTful API and I am clueless how to handle versioning. I have read many discussions and blog articles, which suggest to use the accept header for versioning.
But then I found following website listening popular REST APIs and their versioning method and most of them using the URL for versioning. Why?
Why are most people saying: "Don't use the URL, but use the accept header", but popular APIs using URL?
CONS. It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version). Just like the previous method you should try to avoid this method if you are also versioning resources.
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.
APIs only need to be up-versioned when a breaking change is made. Breaking changes include: a change in the format of the response data for one or more calls. a change in the request or response type (i.e. changing an integer to a float)
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, then URL versioning approach is more widely used.
The Pros and Cons (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:
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