DEV Community

Edison Yap
Edison Yap

Posted on

How do you do API versioning?

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 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 /users now take different params), do you bump the whole /users version, or do you bump that specific POST /users action?
  • 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:

 |> users/
     |> v1/
        |> api.rb
        |> serializer.rb
Enter fullscreen mode Exit fullscreen mode

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 /v1 endpoint 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)

awwsmm profile image
Andrew (he/him)

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.

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.

kspeakman profile image
Kasey Speakman • Edited

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.

voidp34r profile image
Matheus Rafael

interesting your point of view.