#350 REST API Versioning

Nice one Ryan,

Would be good to expand this tutorial on how to secure your API with tokens or usernames and passwords? Also the possibility of using CanCan to authorize the api methods.

I would have it a guess the best place to start would be to create a api base class where most of that work could be done?

Great one. Super useful.

Just one comment: lib/api_constraints.rb has a typo at line 3 @verison instead of @version.

One thing I have started doing recently for a few APIs is to support versioning simply using folders with RABL templating. Depending on your situation, it can greatly reduce code duplication. Simply setup a single api controller and then render the corresponding template based on a version parameter i.e render "#{params[:version]}/show" and then create templates for each version (users/v1/show, users/v2/show). Since the controller between versions is typically largely unchanged in most cases, this may be an alternative approach. If anyone is curious for more details, perhaps I can add a guide to the RABL wiki.

Each time you create a new MIME type name (application/vnd.example.v1, application/vnd.example.v2, ...), a kitten is hurt! don't do that! that's bad!

Use MIME parameters instead: application/vnd.example; version=1, application/vnd.example; version=2, ... (version=, or level=, or v= or whatever you want, this is part of your design).

The semantic of a MIME type is that every document "flagged" with that type share the same "lineage", and that two different names are not related, even if they share a same prefix.

By incorporating a version identifier into the MIME type name, you are making the names distinct and are in the same case as if your V1 API was using text/html documents whereas your V2 now uses image/png pictures instead.

Great episode!
But there is a bug in lib/api_constrains.rb :

def initialize(options)
@verison = options[:version]
@default = options[:default]
end

Should it not be the following?:
@version = options[:version]

because in the matches method below it, you use the @version variable...

Oops, just saw David spotted it also ;)

Ryan, you just read my mind! I've been looking for a good resource on best practice for this so having you create a post like this is a real treat since there's not much info for best practices.

Does anyone know a good technique for auto-generating API documentation?

Ryan, thanks so much for recording this episode. Last week I worked in something similar. Just one thing, I would pass the version as a mime type parameter. Something like:

curl -H "Accept: vnd.myapp+json; version=2"

Here's my implementation.

Do you have any recommendations for handling errors using the correct content type within an API namespace? For example if you 404 by POSTing to /api/products/1 instead of using a PUT, you get the Rails HTML 404 page in the response because the route does not match. Same goes for 500 errors if they ever happen.

Would be nice to get a JSON response for all requests in the namespace.

Thanks Ryan for the examples. Some clients will use multiple Accept header values when they expect to live in mixed environments, so it would be good to put the default version higher in the routes (in the version I read just now, it looks like a client sending v1 and v2 in the Accept header will get v1).

Not sure how you would efficiently use the q parameter (i.e. Accept: application/vnd.myapp+json;v=2;q=1.0,application/vnd.myapp+json;v=1;q=0.9), as ideally the server would select the most-preferred client version that it also supports, but that seems like a lot of overhead just to get strict correctness.

The problem with the default is it will accept any mime type, as it will only check the boolean and not the string:

@default || req.headers['Accept'].include?("application/vnd.example.v#{@version}")

I mean, if we're expecting "application/vnd.github.v1", it will also accept "application/vnd.twitter.v1"

Not being a Rails Expert, why did you wrap the different API Versions in a Module rather than just using a controller?

How would you handle overriding the as_json method for a Polymorphic model?

Once I try to override the query changes to :

... items.type IN ('Api::V1::ProjectsController::Project') ...

Trying to make it works with mongoid. It doesn't seems to work. Product is always empty. What am I doing wrong?

Anyone using mongoid ?

Is there a way this can be implemented where you only define new functionality in new versions? Say for example:

I have a Users controller and a Products controller. Products has stayed the same between V1 and V2, but Users has changed. It would be nice if we could set it up so that if I call for V2 of Products, my application knows it doesn't exist and simply uses the most recent controller version instead (in this case, V1).

Have anyone tried using grape? It's built directly on top of Rack, which would seem to make it quite efficient. I think it also has an interface for oauth authentication.

I dont know how about you guys but i cant seem to get my tests to work.
How do you guys write these tests if your controller is nested inside the modules?

require 'spec_helper'
namespace :api do
  namespace :v1 do
    describe ProductsController do

      describe "GET 'index'" do
        it "returns http success" do
          get 'index'
          response.should be_success
        end
      end
    end    
  end
end

Failures:

  1) ProductsController GET 'index' returns http success
     Failure/Error: get 'index'
     ActionController::RoutingError:
       No route matches {:controller=>"products"}
     # ./spec/controllers/api/v1/products_controller_spec.rb:10:in `block (5 levels) in <top (required)>'

Obviously because the correct route should be:
{:action=>"index", :controller=>"api/v1/products"}

I like using the idea of using the Accepts header for versioning, although it does make it harder to test API versions from a browser's URL bar.

But there's a bug in this code that will be exposed once you reach v10. matches?(req) will return true when the router asks if the request is for v1, because 'application/vnd.example.v10'.includes?('application/vnd.example.v1') is true.

One way to fix this is to reverse the order of your routes file: put newer versions at the top, not at the bottom.

For some reason I can't get my app to work based on the sample code for this screencast. After setting up the routes, api_constraints, and the api/v1/ controller directory structure, API requests fail with the exception:

ActionController::RoutingError (wrong constant name v1):
  app/controllers/api/v1/base_controller.rb:3:in `<module:V1>'
  app/controllers/api/v1/base_controller.rb:2:in `<module:Api>'
  app/controllers/api/v1/base_controller.rb:1:in `<top (required)>'
  app/controllers/api/v1/groups_controller.rb:1:in `<top (required)>'

My controller at app/controllers/api/v1/groups_controller.rb looks like this:

module Api
  module V1
    class GroupsController < ApplicationController
      respond_to :json

      # ... snip ....

    end
  end
end
end

My Routes look like this:

  # ... snip ... 
  namespace :api, defaults: {format: 'json'} do
    scope module: :v1, constraints: ApiConstraints.new(version: 1, default: true) do
      resources :groups
    end
  end
  # ... snip ... 

Anyone else have this problem? Have I missed something?

I can access the '/api/resource.json' but there is an error while trying access '/api/v2/resource.json'

No route matches [GET] "/api/v1/companies/00000000000001/reports.json"

No route matches [GET] "/api/v2/companies/00000000000001/reports.json"

I implemented this for a new API I'm building and my tests caught what I think might be a bug in the case where your default is an earlier version but you want to make later versions available. For example, you have v1, v2, and v3. v2 is still the default and you're testing v3. Because the matcher goes in order, when it hits the default (v2) it will match to that, even if you specified 'v3' in the Accepts header.

Here is how I solved it. I'm a bit of a n00b, so I'm sure you can make it prettier/more efficient.

Created an ACTIVE_API_VERSIONS constant so I know whether the version specified is active, in which case I can ignore the default.

ACTIVE_API_VERSIONS = ['v0', 'v1'] 

Modified the class like so

class ApiConstraints
  def initialize(options)
    @version = options[:version]
    @default = options[:default]
  end

  def matches?(req)
    if req.headers['Accept'] =~ /application\/vnd.example.v([0-9]+)/
      ver = $1.to_i
      ACTIVE_API_VERSIONS.include?("v#{ver}") ? @version == ver : @default
    else
      @default
    end
    # @default || req.headers['Accept'].include?("application/vnd.linguixlabs.v#{@version}")
  end
end

With the default routing:

 resources :products

you'll get routes for #new and #edit, which aren't used in a pure JSON interface. Is there a reason for NOT doing

 resources :products, :except => [:new, :edit]

?

Is it really a good practice to have a default version? There seems to be a big risk in not forcing clients to make a conscious decision on which API version to support since changing the default version will invalidate all clients accessing the API via the default route.

Why put everything in a separate controller for API? Image a separate API registration controller and a standard web controller; changes are made to the web controller forgetting to make the same changes to the API controller.

This is the problem that the respond_to blocks are suppose to help solve.

Take a look at VersionCake ( https://github.com/bwillis/versioncake ); easily set the API version in the request header. The appropriate view is then rendered for the request (e.g. show.v1.json.jbuilder). If the requested version of the view doesn't exist, the next prior version is rendered ensuring backwards compatibility.

I have an older project using Rails 2.3.14 and Ruby 1.8.7. Some of the routing constructs used here don't appear to be available in Rails 2. Any suggestions for how to implement a similar versioning system in Rails 2?

Hi Ryan, nice episode.
Is it possible to speed up APIs? In episode #348 you described The Rails API gem and, if I got the concept, many rails features aren't loaded in order to have faster APIs. Is it possible in some way to exclude libraries only for controllers related to APIs?

Thanks in advance.

Hi, nice episode, very helpful.

But (there is always a but lol) i have a problem ! (2 in fact)

I'm using ruby 3.2.11

if I try to use in my routes.rb :

scope module: :v1, constraints: ApiConstraints.new(version: 1) do

I have an error message 'No route matches [GET] "/dev/v1/media"', if I use a namespace instead (but without constraints) it works! Any idea ? (my first namespace is dev not api)

Other problem, I specified the json format by default in my namespace, set the respond_to :json in my controller but if I use respond_with, got a error message "Missing Template", I need to use :

@media = Medium.all
              respond_to do |format|
                format.json { render json: @media, status: :created }
        end

Any idea ?

Thanks :)

I used rabl in my app. how can I avoid creating controllers which is essentially same as my non-API controllers

One thing to mention is that in the routes file, the default version has to be the last one to be defined.
I had a problem where I added a v2 on top of v1 and made it the default like this:

...
namespace :api, defaults: { format: 'json' } do
  scope module: :v2, constraints: ApiConstraints.new(version: 2, default: true) do
  ...
  end
  scope module: :v1, constraints: ApiConstraints.new(version: 1) do
  ...
  end
end
...

All V1 requests would be redirected to the V2 Controllers

how do you guys test that ApiConstrant ?

and added a new product from curl?

Overriding model in api controller was an excellent piece of code. But can you guide me how and where to put this class in a separate file and include it in api controller.

Hi all

Let's suppose we have an existing rails app (just a basic scaffold - with it's own controllers).

Does this mean, if I am building an API, that I have to write another controller - an API controller?

Would be interested to hear your thoughts. chrs

Ben