API Versioning

[msheakoski]

I'm not sure if it's within the scope of this project, but versioning is an important component of a good API design. Have you seen Versionist? It does a pretty good job of allowing the version to be specified in the Accept header, path, or param. The problems that Versionist and Rails::API solve are complimentary and it may be beneficial to integrate some versioning best practices into this gem or at least lay the groundwork to make it easier to version the API for your app's specific needs.

[carlosantoniodasilva]

I think that how you decide to version your api - if you decide to do it, is a matter of taste, and probably beyond the scope of rails-api. I agree versioning is a good practice, but not required for all applications.

Well, lets keep the discussion open for now, to see people's opinions on that. Thanks!

[jmonteiro]

My first instinct would be to agree with @gmflash and tell that this is really a cool feature to add by default to rails-api. But I think there are a good ammount of developers who aren't interested in mantaining versioning, so dealing this that overhead (even if that's easily disabled) wouldn't be interesting.

So I vote for waiting for the rails-api to mature and grow, and to decide in the feature if this really is a requested by 80% or by 20% of rails-api's "customers" (i.e. if you think this should be actually added, vote it up 👍).

[krainboltgreene]

To be fair, there are a good amount of developers who probably aren't interested in IP Spoofing, ConditionalGet, or timing attacks, but Rails (And Rails::API) makes that choice for them.

[apsoto]

I think versioning should be supported out of the box. Using content negotiation is probably the most unobtrusive so no one complains about it making their URLs ugly with version numbers.

[jmonteiro]

@apsoto and @krainboltgreene have good arguments on API versioning. 👍 on having a default API versioning system supported out of the box.

[plribeiro3000]

👎
If it is easy to integrate, why it should be supported out of the box instead of the guys who need it just do a bundle install?

[krainboltgreene]

The same could be said for literally any of the middleware that come with rails-api. That's not a solid argument.

[plribeiro3000]

@krainboltgreene indeed. Lets see what other people have to say about it. =D

[damien]

+1 here. Every API I've worked on has been for a mobile client. For most mobile clients (especially iOS), you have very little control on when releases happen or when consumers of your API will update.

Smart versioning is the only way I know of to modify an existing API without breaking a lot of consumer implementations or doing a lot of conditional, client specific response handling.

[databyte]

I think the point is that there are other solutions already out there that can be easily integrated.

I don't see that it's the same as more middleware given that Versionist and RocketPants do a good job, you can hand roll your own as Ryan Bates demonstrated, and it's mostly just about routes.

The examples of "IP Spoofing, ConditionalGet, or timing attacks" are using existing middleware modules already provided by Rack. This gem doesn't actually provide much in terms of new middleware modules, it's mostly an opinionated selection of middleware that's already in Rack and ActionDispatch.

I suggest education via the README is sufficient. You can create a section about Versioning and pop in a few links like I did above.

[bploetz]

This is a slippery slope. If you decide to include support for a feature like versioning, then do you also include support for features like authentication/authorization? How about rate-limiting? Where do you draw the line?

I say keep features like this out of rails-api itself, and let developers pick and choose the features they want to enable in their APIs via gem dependencies as they normally would.

[afeld]

What if this gem stays nice and general, but someone can build a gem on top of it that has built-in generators for Versionist or whatever. That way rails-api stays lean, but people who want the good-practice-out-of-the-box can have it.

[jsmestad]

I like @afeld's idea

[damien]

+1 @afeld

[andrewhavens]

@afeld Do you mean a gem named something like rails-api-versions that sets up some default dependencies (Versionist, etc) and has a nice Readme that explains what the best-practice is? That would be a nice approach.

[afeld]

I guess it could be a special generator, really. Jeweler is a good example of a flexible one, particularly around setup of the test framework(s).

[plribeiro3000]

Well, rspec-rails and factory_girl_rails are another good examples. =D

[mwoods79]

+1 @afeld

[steveklabnik]

We've had a pretty good discussion here. Obviously versioning APIs is important to people, but since the reason that rails-api exists is to modify the basic Rails stack, I don't think adding another gem helps with that.

That said, if someone can demonstrate a way in which we can help gems like versionist do their job better, absolutely, let's help them out.

Given that this discussion has played out, I'm giving it a close. If anyone has concrete proposals on this topic, please submit a pull request. Thanks all! ❤️

[bploetz]

FYI, my testing shows that versionist works just fine with rails-api apps, so if you want versioning suppport, simply add the following to your rails-api app's Gemfile:

gem 'versionist'

If you run into any problems or have any suggestions, please file an issue/pull request. Thanks.