{"id":16957007,"url":"https://github.com/jgraichen/api-responder","last_synced_at":"2026-04-17T02:32:37.181Z","repository":{"id":6893886,"uuid":"8143529","full_name":"jgraichen/api-responder","owner":"jgraichen","description":"ApiResponder simplifies version dependent rendering of API resources.","archived":false,"fork":false,"pushed_at":"2022-01-24T18:48:44.000Z","size":14,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-05T17:52:55.915Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgraichen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-11T18:18:39.000Z","updated_at":"2022-01-24T18:48:35.000Z","dependencies_parsed_at":"2022-09-09T13:21:58.241Z","dependency_job_id":null,"html_url":"https://github.com/jgraichen/api-responder","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jgraichen/api-responder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgraichen%2Fapi-responder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgraichen%2Fapi-responder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgraichen%2Fapi-responder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgraichen%2Fapi-responder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgraichen","download_url":"https://codeload.github.com/jgraichen/api-responder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgraichen%2Fapi-responder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264502166,"owners_count":23618557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T22:16:36.570Z","updated_at":"2026-04-17T02:32:32.114Z","avatar_url":"https://github.com/jgraichen.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Responders::ApiResponder [![Build Status](https://travis-ci.org/jgraichen/api-responder.png?branch=master)](https://travis-ci.org/jgraichen/api-responder)\n\n`ApiResponder` simplifies version dependent rendering of API resources using a custom responder and a mixin for decorators or models (decorators are recommended).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'api-responder'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install api-responder\n\n## Usage\n\nAdd `Responders::ApiResponder` to your responder chain:\n\n```ruby\nclass AppResponder \u003c Responder\n  include Responders::ApiResponder\nend\n\nclass MyController \u003c ApplicationController\n  self.responder = AppResponder\nend\n```\n\nOr use it with [plataformatec/responders](https://github.com/plataformatec/responders):\n\n```ruby\nclass MyController \u003c ApplicationController\n  responders Responders::ApiResponder\nend\n```\n\nThis 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`:\n\n```ruby\nclass MyModel\n  include ApiResponder::Formattable\n\n  api_formats :xml\n\n  def as_api_v1\n    {\n      id: id,\n      first_name: name.split.first\n      last_name: name.split.last\n    }\n  end\n\n  def as_api_v2\n    as_api_v1.merge name: \"#{first_name} #{last_name}\"\n  end\nend\n```\n\nThis 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.\n\nThe 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:\n\n```ruby\nclass MyController \u003c ApplicationController\n  responders Responders::ApiResponder\n\n  def api_version\n    return $1 if request.headers[\"Accept\"] =~ /vnd\\.myapp.v(\\d+)/\n  end\nend\n```\n\nI 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)):\n\n```ruby\nclass User \u003c ActiveRecord::Base\n  attr_accessible :id, :first_name, :last_name\nend\n\nclass UserDecorator \u003c Draper::Decorator\n  include ApiResponder::Formattable\n  decorates :user\n\n  api_formats :msgpack\n\n  def name\n    \"#{first_name} #{last_name}\"\n  end\n\n  def as_api_v1\n    {\n      id: model.id,\n      created_at: model.created_at.utc.iso8601,\n      name: name\n    }\n  end\nend\n\nclass UsersController \u003c ApplicationController\n  responders Responders::ApiResponder,\n    Responders::DecorateResponder\n\n  respond_to :json, :xml, :msgpack\n  rescue_from ApiResponder::Formattable::UnsupportedVersion do\n    head :not_acceptable\n  end\n\n  def index\n    respond_with User.scoped\n  end\n\n  def api_version\n    return $1 if request.headers[\"Accept\"] =~ /vnd\\.myapp.v(\\d+)/\n  end\nend\n```\n\nWhen `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:\n\n```ruby\nrescue_from ApiResponder::Formattable::UnsupportedVersion do\n  head :not_acceptable\nend\n```\n\nCheck out [jgraichen/paginate-responder](https://github.com/jgraichen/paginate-responder) for automagic pagination support including HTTP Link headers.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Write tests for your feature\n4. Add your feature\n5. Commit your changes (`git commit -am 'Add some feature'`)\n6. Push to the branch (`git push origin my-new-feature`)\n7. Create new Pull Request\n\n## License\n\n[MIT License](http://www.opensource.org/licenses/mit-license.php)\n\nCopyright (c) 2013 Jan Graichen\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgraichen%2Fapi-responder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgraichen%2Fapi-responder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgraichen%2Fapi-responder/lists"}