API Versioning using Custom Request Header/“Accept” header

[thientd87]

https://restfulapi.net/versioning/

Accept Header

`
Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0

`

Pros: Allows us to version a single resource representation instead of versioning the entire API, which gives us a more granular control over versioning. Creates a smaller footprint. Doesn’t require implementing URI routing rules.
Cons: Requiring HTTP headers with media types makes it more difficult to test and explore the API using a browser

Custom Request Header

Accept-version: v1 Accept-version: v2
REST APIs can also be versioned by providing custom headers with the version number included as an attribute.The main difference between this approach and the two previous ones is that it doesn’t clutter the URI with versioning information.

Pros: It doesn’t clutter the URI with versioning information
Cons: It requires custom headers

https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/

[thientd87]

some best practices

https://www.linkedin.com/pulse/best-practices-your-api-versioning-strategy-omar-ismail/

[marc-costea]

I think "versions per API" are sufficiently fine-grained.
If we make it even finer, i.e. per resource representation, then it quickly becomes very confusing, especially for unexperiences Qilin.Cloud 3rd party devs. Therefore, rather rare version jumps with more content, not more often than every x months per API.

From my previous experience as a developer working with APIs of different marketplaces, I can only say that usually several APIs are consumed per product and company. If one of them stands out due to extremely frequent updates, this is usually noticed negatively (especially in the business management level), as it is felt that it causes "constant adaptation work" (and costs), or at least more than the others.

Therefore, Qilin.Cloud should pay attention to a fine balance on "not too often", but "comprehensive" bundled and everytime when neccessary. If Qilin.Cloud releases more updates, then it is imperative to pay attention to backward compatibility within the same minor version.
Just check the GitHub API. 4 Versions in 13 years 😎

But, I also know the discussions when it comes to versioning of restulf API -> Header vs URL.
In my eyes it is necessary to differenciate between format versioning and entity versioning.
What Qilin.Cloud have is entity versioning. (Read more about it here

The question now is:
Should we stay with only breaking changes and the major version number, which leads into entity versioning. Because on entity version the resources are not interchangeable. If so, keeping the version in the URL makes sense, because every new version requires new models and there is not incorrectly selected version by mistake.
But if we say, there will be also smaller changes -like minor changes- which ARE backwards compatible, the its more like a format versioning and should be choosen by the header.

Wwhatever we decide, if no version is set (in url or in header) we should automatically route to the newest version, so its possible for API consumers to subscribe them in their IDEs.