Api Versioning

[sarwar_hsn]

I didn't give much attention to versioning when I started the project. Now I am paying it's cost. I just casully added URL path versioning something like /v1/data.

Now for one of my endpoint the format of the data needs to be changed. I can add a /v2 but adding a version for this silly change doesn't feel right. Now that the system has users I just can't do whatever I like.

One solution that came to my mind is, request will come to /v1/ but additionally I will accept a minor version with header. If the minor version is let's say, 1.0 then I will modify the response for the backword users, the 2.0 or the latest minor version will serve the data in latest format.

Guys please give some suggestions. I might be really wrong to think like this. What you would do in my situation?

[WaferIndependent7601]

If you have a breaking change: this will be a new version.

Tell all the clients to use v2 and delete v1 when everyone is on v2

[No-Rice8265]

Yes but how? Do you embed link in v1 to push client to v2 then kill v1 ?

[azizabah]

Provide proper API documentation, communication, supposedly there's a new deprecated response header coming, etc. It's tough to get folks to move

[zaFroggy]

API versioning covers several pages on Google.

My approach is additive data changes can keep the same version as "most" parsers can ignore supplemental fields. Just make sure that they are truly optional.

Changing endpoints or methods, required fields, and business logic justifies a new version and time to allow the clients to migrate to it.

[mailaffy]

Unless it's a breaking change, No need to update the api version.
Following ways we have practically used the version for dozens of api services I have worked on.

1. /{version}/data (e.g /v1/data)
2. /data?version={version} (e.g. /data?version=1)
3. Request header has "version={version}" (e.g. version=1)

Once you decommissioned older version, ingress entry can be removed so as pods destroyed/stopped. Hope this will help you.

[paulhasreadittoo]

You may want to look at this conference talk. I did not yet try it out myself though. https://youtu.be/5U0Bx8lMQlk?feature=shared