https://github.com/jgraichen/api-responder
ApiResponder simplifies version dependent rendering of API resources.
https://github.com/jgraichen/api-responder
Last synced: 2 months ago
JSON representation
ApiResponder simplifies version dependent rendering of API resources.
- Host: GitHub
- URL: https://github.com/jgraichen/api-responder
- Owner: jgraichen
- License: mit
- Created: 2013-02-11T18:18:39.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2022-01-24T18:48:44.000Z (over 4 years ago)
- Last Synced: 2025-07-05T17:52:55.915Z (12 months ago)
- Language: Ruby
- Size: 13.7 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Responders::ApiResponder [](https://travis-ci.org/jgraichen/api-responder)
`ApiResponder` simplifies version dependent rendering of API resources using a custom responder and a mixin for decorators or models (decorators are recommended).
## Installation
Add this line to your application's Gemfile:
gem 'api-responder'
And then execute:
$ bundle
Or install it yourself as:
$ gem install api-responder
## Usage
Add `Responders::ApiResponder` to your responder chain:
```ruby
class AppResponder < Responder
include Responders::ApiResponder
end
class MyController < ApplicationController
self.responder = AppResponder
end
```
Or use it with [plataformatec/responders](https://github.com/plataformatec/responders):
```ruby
class MyController < ApplicationController
responders Responders::ApiResponder
end
```
This will add an API version parameter to the options hash for formatting methods like `as_json`. You can override the formatting methods or just include `ApiResponder::Formattable`:
```ruby
class MyModel
include ApiResponder::Formattable
api_formats :xml
def as_api_v1
{
id: id,
first_name: name.split.first
last_name: name.split.last
}
end
def as_api_v2
as_api_v1.merge name: "#{first_name} #{last_name}"
end
end
```
This will add a handler for XML. You can specify any format your want. `ApiResponder::Formattable` will override the `to_{format}` (e.g. `to_xml`) method to call `to_{format}` on the API specific hash. JSON is supported via `as_json` by default.
The only included method to detect API version is matching the URL path `/api/v(\d+)`. Or you can add an `api_version` method to your controller:
```ruby
class MyController < ApplicationController
responders Responders::ApiResponder
def api_version
return $1 if request.headers["Accept"] =~ /vnd\.myapp.v(\d+)/
end
end
```
I recommend using `ApiResponder` in combination with [jgraichen/decorate-responder](https://github.com/jgraichen/decorate-responder) and the decorator pattern (like [draper](https://github.com/drapergem/draper)):
```ruby
class User < ActiveRecord::Base
attr_accessible :id, :first_name, :last_name
end
class UserDecorator < Draper::Decorator
include ApiResponder::Formattable
decorates :user
api_formats :msgpack
def name
"#{first_name} #{last_name}"
end
def as_api_v1
{
id: model.id,
created_at: model.created_at.utc.iso8601,
name: name
}
end
end
class UsersController < ApplicationController
responders Responders::ApiResponder,
Responders::DecorateResponder
respond_to :json, :xml, :msgpack
rescue_from ApiResponder::Formattable::UnsupportedVersion do
head :not_acceptable
end
def index
respond_with User.scoped
end
def api_version
return $1 if request.headers["Accept"] =~ /vnd\.myapp.v(\d+)/
end
end
```
When `ApiResponder::Formattable` receives nil as API version or the resource does not have a matching `as_api_v` method an `UnsupportedVersion` error will be raised. You can catch that exception and for example return a `406` status code:
```ruby
rescue_from ApiResponder::Formattable::UnsupportedVersion do
head :not_acceptable
end
```
Check out [jgraichen/paginate-responder](https://github.com/jgraichen/paginate-responder) for automagic pagination support including HTTP Link headers.
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Write tests for your feature
4. Add your feature
5. Commit your changes (`git commit -am 'Add some feature'`)
6. Push to the branch (`git push origin my-new-feature`)
7. Create new Pull Request
## License
[MIT License](http://www.opensource.org/licenses/mit-license.php)
Copyright (c) 2013 Jan Graichen