1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
# The built-in XML/JSON support of Rails is great but:
# You surely don’t want to expose your models always with all attributes.
#
# acts_as_api 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][b1] or [RestKit][r1] (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.
# [b1]: http://documentcloud.github.com/backbone
# [r1]: http://restkit.org
# ***
### 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 acts_as_api 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 acts_as_api
# 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][w1]
# * [Include child associations (if they also act_as_api this will be considered)][w2]
# * [Include lambdas and Procs][w3]
# * [Call methods of a parent association][w4]
# * [Call scopes of your model or child associations][w5]
# * [Rename attributes, methods, associations][w6]
# * [Create your own hierarchies][w7]
#
# You can find more advanced examples in the [Github Wiki][wi]
#
# [wi]: https://github.com/fabrik42/acts_as_api/wiki/
# [w1]: https://github.com/fabrik42/acts_as_api/wiki/Calling-a-method-of-the-model
# [w2]: https://github.com/fabrik42/acts_as_api/wiki/Including-a-child-association
# [w3]: https://github.com/fabrik42/acts_as_api/wiki/Calling-a-lambda-in-the-api-template
# [w4]: https://github.com/fabrik42/acts_as_api/wiki/Calling-a-method-of-the-model
# [w5]: https://github.com/fabrik42/acts_as_api/wiki/Calling-a-scope-of-a-sub-resource
# [w6]: https://github.com/fabrik42/acts_as_api/wiki/Renaming-an-attribute
# [w7]: https://github.com/fabrik42/acts_as_api/wiki/Creating-a-completely-different-response-structure
# ***
### Links
# * Check out the [source code on Github][so]
# * For more usage examples visit the [wiki][wi]
# * Found a bug or do you have a feature request? [issue tracker][to]
# * [Docs][do]
#
# [so]: https://github.com/fabrik42/acts_as_api/
# [wi]: https://github.com/fabrik42/acts_as_api/wiki/
# [to]: https://github.com/fabrik42/acts_as_api/issues
# [do]: http://rdoc.info/github/fabrik42/acts_as_api
|
