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 /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:

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 /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?