# acts_as_api

Makes creating XML/JSON responses in Rails 3, 4 and 5 easy and fun.

¶

The built-in XML/JSON support of Rails is great but: You surely don’t want to expose your models always with all attributes.

actsasapi enriches the models and controllers of your app in a rails-like way so you can easily determine how your API responses should look like.

¶

## Features

- DRY templates for your api responses
- Ships with support for ActiveRecord and Mongoid
- Support for Rails 3, 4 and 5 Responders
- Plays very well together with client libs like Backbone.js or RestKit (iOS).
- Easy but very flexible syntax for defining the templates
- XML, JSON and JSON-P support out of the box, easy to extend
- Support for meta data like pagination info, etc...
- Minimal dependecies (you can also use it without Rails)
- Supports multiple api rendering templates for a models. This is especially useful for API versioning or for example for private vs. public access points to a user’s profile.

¶

## Rails 3.x Quickstart

¶

Add to gemfile

    gem 'acts_as_api'

¶

Update your bundle

    bundle install

¶

### Setting up your Model

¶

Given you have a model `User`. If you only want to expose the `first_name` and `last_name` attribute of a user via your api, you would do something like this:

¶

Within your model:

First you activate actsasapi for your model by calling `acts_as_api`.

Then you define an api template to render the model with `api_accessible`.

    class User < ActiveRecord::Base

      acts_as_api

      api_accessible :name_only do |template|
        template.add :first_name
        template.add :last_name
      end

    end

¶

An API template with the name `:name_only` was created.

See below how to use it in the controller:

¶

### Setting up your Controller

¶

Now you just have to exchange the `render` method in your controller for the `render_for_api` method.

    class UsersController < ApplicationController

      def index
        @users = User.all

¶

Note that it's wise to add a `root` param when rendering lists.

        respond_to do |format|
          format.xml  { render_for_api :name_only, xml: @users,  root: :users }
          format.json { render_for_api :name_only, json: @users, root: :users }
        end
      end

      def show
        @user = User.find(params[:id])

        respond_to do |format|
          format.xml  { render_for_api :name_only, xml: @user  }
          format.json { render_for_api :name_only, json: @user }
        end
      end

    end

¶

### That's it!

¶

Try it. The JSON response of #show should now look like this:

Other attributes of the model like `created_at` or `updated_at` won’t be included because they were not listed by `api_accessible` in the model.

    {
      "user": {
        "first_name": "John",
        "last_name":  "Doe"
      }
    }

¶

¶

## But wait! ... there's more

Often the pure rendering of database values is just not enough, so actsasapi provides you some tools to customize your API responses.

¶

### What can I include in my responses?

You can do basically anything:

- Include attributes and all other kinds of methods of your model
- Include child associations (if they also actasapi this will be considered)
- Include lambdas and Procs
- Call methods of a parent association
- Call scopes of your model or child associations
- Rename attributes, methods, associations
- Create your own hierarchies

You can find more advanced examples in the Github Wiki

¶

¶

## Links

- Check out the source code on Github
- For more usage examples visit the wiki
- Found a bug or do you have a feature request? issue tracker
- Docs

Fork me on GitHub