Recently been thinking how to do API versionings, and realised there's multiple ways of doing things. I do not think there's only one right way , b...
For further actions, you may consider blocking this person and/or reporting abuse
I'm a fan of date-based versioning.
Makes it really easy to tell which is the most recent version! And you don't have to worry about major and minor increments or anything like that.
I have done both of the types you have suggested.
Anything after the v1 gets modified though. So I never assume /v1/users can be bumped without also bumping. /v1/users/list for example. So the choice to bump users impacts everything to the right.
I am also a fan of the date based approach, except you have to have the infrastructure to support that range of granularity, or have very well planned releases to prevent high granularity.
I think for most people, version based is best. But I would keep the version as high as possible unless you can’t plan your endpoints holistically. For me it’s important to keep all endpoints similar. Same style, same verbiage, etc. But if your growing and this is something you can’t plan out, having them on the end of the resource /users/v1 can be helpful.
Additionally tools like AWS API gateway are not great with versions that sit before the resource when pointing to a instance. Llambdas seems to be a different story.
I'm a big fan of additive versioning. That is, you don't make breaking changes to public APIs. Instead you add a new operation. People can still use the old one until they get around to upgrading. Rich Hickey had a great talk about this. Note: The video is very in depth about different levels of versioning, so buckle up before you watch. He addresses APIs specifically toward the end.
youtu.be/oyLBGkS5ICk?t=1189
interesting your point of view.