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 , but I am really curious to hear what you people have to add!
There's mainly a couple of questions I'm wondering (I wish dev.to has the polls features out already!)
- Do you prefix the version to the resource, or suffix it to the resource? e.g:
/v1/users/or/users/v1/? - When you have a breaking change for a specific action (
POST /usersnow take different params), do you bump the whole/usersversion, or do you bump that specificPOST /usersaction? - Where do you keep the serializers? in the same folder, or different?
- APIs are usually backed up by business logics, in some cases being called Service Objects in Rubyland — do you guys also bump your Services when your API is updated?
For more concrete example, let's say you have an API to reset password for user, eg: /v1/users/:id/reset_password, then for some reason you have a breaking change for /reset_password. What do you do now?
- Bump the entire resource to
v2(e.g:/v2/users,/v2/users/:id,/v2/users/:id/reset_password) - Bump only specific action (e.g:
/v1/users, /v1/users/:id, /v2/users/:id/reset_password) - Rethink versioning to scope by action instead (e.g:
/users/v2/:id/reset_password)
In my opinion, this makes sense to me:
api/
|> users/
|> v1/
|> api.rb
|> serializer.rb
Couple of things I'm doing here:
- I suffix the version to resource, not prefix (breaks REST)
- I place serializers and endpoint in the same file
So whenever there's a breaking change in API (e.g: parameter changes), I think it logically makes more sense to bump the whole resource even if it's just one action, reason being as follow:
-
Deprecation is easier - if you know that
/v1endpoint is not being used anymore (through your APM), then just delete off the whole folder itself without worrying it'll impact other part of the app. No need to ask questions like: "v1 is still in use except for this specific action, for that it'll be in v2" - Locality - I think that inherently serializers are just a way to serialize your data into JSON, and so it should be versioned the same way as your API. By putting them in the same folder, it ensures that you're more likely to update both of them at the same time, and it also makes it much easier for developers to see which API is using which serializer.
So, what do you guys think/do currently?
Top comments (4)
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.