ApiVersioning

Model based API versioning. Extracted from launch.ly.

Installation

Add this line to your application's Gemfile:

gem 'api_versioning'

And then execute:

$ bundle

Or install it yourself as:

$ gem install api_versioning    

Setting up an API model (presenter)

Let's create a model that will present our API response.

Under your models directory, create a folder called api. Create your model that will handle API Responses in that api_folder, for example posts_api.rb.

class Api::PostsApi < Api::BaseApi

	def v1(posts)

		Jbuilder.encode do |json|
			json.awesome_response 'Hello World'
		end

	end

end

Now if I wanted to add a new API version, I would do something like this

class Api::PostsApi < Api::BaseApi

	def v1(posts)

		Jbuilder.encode do |json|
			json.awesome_response 'Hello World'
		end

	end

	def v1_1(posts)

		Jbuilder.encode do |json|
			json.posts items do |json, post|
				timestamps json, post
				json.post post.title
			end
		end

	end

end

I used DHH JBuilder to format out the JSON responses, but you can use whatever you like.

Setting up your Controller

There is a method called render_json that accepts the collections that you would like rendered as an API response. Here is a sample implementation:

class PostsController < ApplicationController

	def index

		@posts = Post.all
      
		respond_to do |format|
			format.json { render_json posts: @posts }
		end

	end

end

Additionally, you can also pass in multiple parameters to the presenter.

render_json posts: { posts: @posts, signed_in: user_signed_in? }

Then, in the presenter, you can access your parameters like ...

class Api::PostsApi < Api::BaseApi

	def v1(options)
	
		posts = options[:posts]
		signed_in = options[:signed_in]

		Jbuilder.encode do |json|
			json.awesome_response 'Hello World'
		end

	end

end

Requesting an API Version

About API Version Numbers

We have adopted API version numbers that consist of a major and minor API version number. The major and minor API version number consists of digits 0-9 and are spearated by an underscore. For example, 1_2 refers to API version 1.2

if an API version number is not detected, the latest version is used.

Requesting an API Version by Request Header

curl -H "X-Api-Version:v1_2" http://localhost/posts.json

Requesting an API Version by Query String Parameter

Just add the api_version parameter to your request's query string like this

http://localhost/posts.json?api_version=v1_2

Order of Precedence

If you request API versions via multiple methods, the following order of precedence will apply:

1. Request Parameter params['api_version']
2. Request Header HTTP_X_API_VERSION

Building locally

bundle exec rake -f test/dummy/Rakefile db:migrate db:test:prepare rake

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request