DEV Community


Discussion on: How do you do API versioning?

khrome83 profile image
Zane Milakovic

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.