Skip to content
This repository has been archived by the owner. It is now read-only.
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
app
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

ApiVersioning

Model based API versioning. Extracted from launch.ly.

Build Status

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

About

Model based API versioning.

Resources

License

You can’t perform that action at this time.