rest_framework 0.8.15 → 0.8.17
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/VERSION +1 -1
- data/app/views/layouts/rest_framework.html.erb +149 -128
- data/app/views/rest_framework/_head.html.erb +249 -28
- data/app/views/rest_framework/_html_form.html.erb +55 -3
- data/app/views/rest_framework/_raw_form.html.erb +31 -3
- data/docs/CNAME +1 -0
- data/docs/Gemfile +4 -0
- data/docs/Gemfile.lock +264 -0
- data/docs/_config.yml +17 -0
- data/docs/_guide/1_routers.md +110 -0
- data/docs/_guide/2_controller_mixins.md +293 -0
- data/docs/_guide/3_serializers.md +60 -0
- data/docs/_guide/4_filtering_and_ordering.md +41 -0
- data/docs/_guide/5_pagination.md +21 -0
- data/docs/_includes/anchor_headings.html +144 -0
- data/docs/_includes/head.html +35 -0
- data/docs/_includes/header.html +58 -0
- data/docs/_layouts/default.html +11 -0
- data/docs/assets/css/rest_framework.css +159 -0
- data/docs/assets/images/favicon.ico +0 -0
- data/docs/assets/js/rest_framework.js +132 -0
- data/docs/index.md +133 -0
- data/lib/rest_framework/controller_mixins/base.rb +10 -3
- data/lib/rest_framework/controller_mixins/models.rb +120 -44
- data/lib/rest_framework/filters.rb +7 -9
- data/lib/rest_framework/serializers.rb +35 -12
- data/lib/rest_framework/utils.rb +11 -2
- data/lib/rest_framework/version.rb +4 -1
- data/lib/rest_framework.rb +2 -8
- metadata +22 -6
- data/app/views/rest_framework/_form_routes.html.erb +0 -10
data/docs/Gemfile.lock
ADDED
@@ -0,0 +1,264 @@
|
|
1
|
+
GEM
|
2
|
+
remote: https://rubygems.org/
|
3
|
+
specs:
|
4
|
+
activesupport (7.0.4.3)
|
5
|
+
concurrent-ruby (~> 1.0, >= 1.0.2)
|
6
|
+
i18n (>= 1.6, < 2)
|
7
|
+
minitest (>= 5.1)
|
8
|
+
tzinfo (~> 2.0)
|
9
|
+
addressable (2.8.2)
|
10
|
+
public_suffix (>= 2.0.2, < 6.0)
|
11
|
+
coffee-script (2.4.1)
|
12
|
+
coffee-script-source
|
13
|
+
execjs
|
14
|
+
coffee-script-source (1.11.1)
|
15
|
+
colorator (1.1.0)
|
16
|
+
commonmarker (0.23.8)
|
17
|
+
concurrent-ruby (1.2.2)
|
18
|
+
dnsruby (1.61.9)
|
19
|
+
simpleidn (~> 0.1)
|
20
|
+
em-websocket (0.5.3)
|
21
|
+
eventmachine (>= 0.12.9)
|
22
|
+
http_parser.rb (~> 0)
|
23
|
+
ethon (0.16.0)
|
24
|
+
ffi (>= 1.15.0)
|
25
|
+
eventmachine (1.2.7)
|
26
|
+
execjs (2.8.1)
|
27
|
+
faraday (2.7.4)
|
28
|
+
faraday-net_http (>= 2.0, < 3.1)
|
29
|
+
ruby2_keywords (>= 0.0.4)
|
30
|
+
faraday-net_http (3.0.2)
|
31
|
+
ffi (1.15.5)
|
32
|
+
forwardable-extended (2.6.0)
|
33
|
+
gemoji (3.0.1)
|
34
|
+
github-pages (228)
|
35
|
+
github-pages-health-check (= 1.17.9)
|
36
|
+
jekyll (= 3.9.3)
|
37
|
+
jekyll-avatar (= 0.7.0)
|
38
|
+
jekyll-coffeescript (= 1.1.1)
|
39
|
+
jekyll-commonmark-ghpages (= 0.4.0)
|
40
|
+
jekyll-default-layout (= 0.1.4)
|
41
|
+
jekyll-feed (= 0.15.1)
|
42
|
+
jekyll-gist (= 1.5.0)
|
43
|
+
jekyll-github-metadata (= 2.13.0)
|
44
|
+
jekyll-include-cache (= 0.2.1)
|
45
|
+
jekyll-mentions (= 1.6.0)
|
46
|
+
jekyll-optional-front-matter (= 0.3.2)
|
47
|
+
jekyll-paginate (= 1.1.0)
|
48
|
+
jekyll-readme-index (= 0.3.0)
|
49
|
+
jekyll-redirect-from (= 0.16.0)
|
50
|
+
jekyll-relative-links (= 0.6.1)
|
51
|
+
jekyll-remote-theme (= 0.4.3)
|
52
|
+
jekyll-sass-converter (= 1.5.2)
|
53
|
+
jekyll-seo-tag (= 2.8.0)
|
54
|
+
jekyll-sitemap (= 1.4.0)
|
55
|
+
jekyll-swiss (= 1.0.0)
|
56
|
+
jekyll-theme-architect (= 0.2.0)
|
57
|
+
jekyll-theme-cayman (= 0.2.0)
|
58
|
+
jekyll-theme-dinky (= 0.2.0)
|
59
|
+
jekyll-theme-hacker (= 0.2.0)
|
60
|
+
jekyll-theme-leap-day (= 0.2.0)
|
61
|
+
jekyll-theme-merlot (= 0.2.0)
|
62
|
+
jekyll-theme-midnight (= 0.2.0)
|
63
|
+
jekyll-theme-minimal (= 0.2.0)
|
64
|
+
jekyll-theme-modernist (= 0.2.0)
|
65
|
+
jekyll-theme-primer (= 0.6.0)
|
66
|
+
jekyll-theme-slate (= 0.2.0)
|
67
|
+
jekyll-theme-tactile (= 0.2.0)
|
68
|
+
jekyll-theme-time-machine (= 0.2.0)
|
69
|
+
jekyll-titles-from-headings (= 0.5.3)
|
70
|
+
jemoji (= 0.12.0)
|
71
|
+
kramdown (= 2.3.2)
|
72
|
+
kramdown-parser-gfm (= 1.1.0)
|
73
|
+
liquid (= 4.0.4)
|
74
|
+
mercenary (~> 0.3)
|
75
|
+
minima (= 2.5.1)
|
76
|
+
nokogiri (>= 1.13.6, < 2.0)
|
77
|
+
rouge (= 3.26.0)
|
78
|
+
terminal-table (~> 1.4)
|
79
|
+
github-pages-health-check (1.17.9)
|
80
|
+
addressable (~> 2.3)
|
81
|
+
dnsruby (~> 1.60)
|
82
|
+
octokit (~> 4.0)
|
83
|
+
public_suffix (>= 3.0, < 5.0)
|
84
|
+
typhoeus (~> 1.3)
|
85
|
+
html-pipeline (2.14.3)
|
86
|
+
activesupport (>= 2)
|
87
|
+
nokogiri (>= 1.4)
|
88
|
+
http_parser.rb (0.8.0)
|
89
|
+
i18n (1.12.0)
|
90
|
+
concurrent-ruby (~> 1.0)
|
91
|
+
jekyll (3.9.3)
|
92
|
+
addressable (~> 2.4)
|
93
|
+
colorator (~> 1.0)
|
94
|
+
em-websocket (~> 0.5)
|
95
|
+
i18n (>= 0.7, < 2)
|
96
|
+
jekyll-sass-converter (~> 1.0)
|
97
|
+
jekyll-watch (~> 2.0)
|
98
|
+
kramdown (>= 1.17, < 3)
|
99
|
+
liquid (~> 4.0)
|
100
|
+
mercenary (~> 0.3.3)
|
101
|
+
pathutil (~> 0.9)
|
102
|
+
rouge (>= 1.7, < 4)
|
103
|
+
safe_yaml (~> 1.0)
|
104
|
+
jekyll-avatar (0.7.0)
|
105
|
+
jekyll (>= 3.0, < 5.0)
|
106
|
+
jekyll-coffeescript (1.1.1)
|
107
|
+
coffee-script (~> 2.2)
|
108
|
+
coffee-script-source (~> 1.11.1)
|
109
|
+
jekyll-commonmark (1.4.0)
|
110
|
+
commonmarker (~> 0.22)
|
111
|
+
jekyll-commonmark-ghpages (0.4.0)
|
112
|
+
commonmarker (~> 0.23.7)
|
113
|
+
jekyll (~> 3.9.0)
|
114
|
+
jekyll-commonmark (~> 1.4.0)
|
115
|
+
rouge (>= 2.0, < 5.0)
|
116
|
+
jekyll-default-layout (0.1.4)
|
117
|
+
jekyll (~> 3.0)
|
118
|
+
jekyll-feed (0.15.1)
|
119
|
+
jekyll (>= 3.7, < 5.0)
|
120
|
+
jekyll-gist (1.5.0)
|
121
|
+
octokit (~> 4.2)
|
122
|
+
jekyll-github-metadata (2.13.0)
|
123
|
+
jekyll (>= 3.4, < 5.0)
|
124
|
+
octokit (~> 4.0, != 4.4.0)
|
125
|
+
jekyll-include-cache (0.2.1)
|
126
|
+
jekyll (>= 3.7, < 5.0)
|
127
|
+
jekyll-mentions (1.6.0)
|
128
|
+
html-pipeline (~> 2.3)
|
129
|
+
jekyll (>= 3.7, < 5.0)
|
130
|
+
jekyll-optional-front-matter (0.3.2)
|
131
|
+
jekyll (>= 3.0, < 5.0)
|
132
|
+
jekyll-paginate (1.1.0)
|
133
|
+
jekyll-readme-index (0.3.0)
|
134
|
+
jekyll (>= 3.0, < 5.0)
|
135
|
+
jekyll-redirect-from (0.16.0)
|
136
|
+
jekyll (>= 3.3, < 5.0)
|
137
|
+
jekyll-relative-links (0.6.1)
|
138
|
+
jekyll (>= 3.3, < 5.0)
|
139
|
+
jekyll-remote-theme (0.4.3)
|
140
|
+
addressable (~> 2.0)
|
141
|
+
jekyll (>= 3.5, < 5.0)
|
142
|
+
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
|
143
|
+
rubyzip (>= 1.3.0, < 3.0)
|
144
|
+
jekyll-sass-converter (1.5.2)
|
145
|
+
sass (~> 3.4)
|
146
|
+
jekyll-seo-tag (2.8.0)
|
147
|
+
jekyll (>= 3.8, < 5.0)
|
148
|
+
jekyll-sitemap (1.4.0)
|
149
|
+
jekyll (>= 3.7, < 5.0)
|
150
|
+
jekyll-swiss (1.0.0)
|
151
|
+
jekyll-theme-architect (0.2.0)
|
152
|
+
jekyll (> 3.5, < 5.0)
|
153
|
+
jekyll-seo-tag (~> 2.0)
|
154
|
+
jekyll-theme-cayman (0.2.0)
|
155
|
+
jekyll (> 3.5, < 5.0)
|
156
|
+
jekyll-seo-tag (~> 2.0)
|
157
|
+
jekyll-theme-dinky (0.2.0)
|
158
|
+
jekyll (> 3.5, < 5.0)
|
159
|
+
jekyll-seo-tag (~> 2.0)
|
160
|
+
jekyll-theme-hacker (0.2.0)
|
161
|
+
jekyll (> 3.5, < 5.0)
|
162
|
+
jekyll-seo-tag (~> 2.0)
|
163
|
+
jekyll-theme-leap-day (0.2.0)
|
164
|
+
jekyll (> 3.5, < 5.0)
|
165
|
+
jekyll-seo-tag (~> 2.0)
|
166
|
+
jekyll-theme-merlot (0.2.0)
|
167
|
+
jekyll (> 3.5, < 5.0)
|
168
|
+
jekyll-seo-tag (~> 2.0)
|
169
|
+
jekyll-theme-midnight (0.2.0)
|
170
|
+
jekyll (> 3.5, < 5.0)
|
171
|
+
jekyll-seo-tag (~> 2.0)
|
172
|
+
jekyll-theme-minimal (0.2.0)
|
173
|
+
jekyll (> 3.5, < 5.0)
|
174
|
+
jekyll-seo-tag (~> 2.0)
|
175
|
+
jekyll-theme-modernist (0.2.0)
|
176
|
+
jekyll (> 3.5, < 5.0)
|
177
|
+
jekyll-seo-tag (~> 2.0)
|
178
|
+
jekyll-theme-primer (0.6.0)
|
179
|
+
jekyll (> 3.5, < 5.0)
|
180
|
+
jekyll-github-metadata (~> 2.9)
|
181
|
+
jekyll-seo-tag (~> 2.0)
|
182
|
+
jekyll-theme-slate (0.2.0)
|
183
|
+
jekyll (> 3.5, < 5.0)
|
184
|
+
jekyll-seo-tag (~> 2.0)
|
185
|
+
jekyll-theme-tactile (0.2.0)
|
186
|
+
jekyll (> 3.5, < 5.0)
|
187
|
+
jekyll-seo-tag (~> 2.0)
|
188
|
+
jekyll-theme-time-machine (0.2.0)
|
189
|
+
jekyll (> 3.5, < 5.0)
|
190
|
+
jekyll-seo-tag (~> 2.0)
|
191
|
+
jekyll-titles-from-headings (0.5.3)
|
192
|
+
jekyll (>= 3.3, < 5.0)
|
193
|
+
jekyll-watch (2.2.1)
|
194
|
+
listen (~> 3.0)
|
195
|
+
jemoji (0.12.0)
|
196
|
+
gemoji (~> 3.0)
|
197
|
+
html-pipeline (~> 2.2)
|
198
|
+
jekyll (>= 3.0, < 5.0)
|
199
|
+
kramdown (2.3.2)
|
200
|
+
rexml
|
201
|
+
kramdown-parser-gfm (1.1.0)
|
202
|
+
kramdown (~> 2.0)
|
203
|
+
liquid (4.0.4)
|
204
|
+
listen (3.8.0)
|
205
|
+
rb-fsevent (~> 0.10, >= 0.10.3)
|
206
|
+
rb-inotify (~> 0.9, >= 0.9.10)
|
207
|
+
mercenary (0.3.6)
|
208
|
+
mini_portile2 (2.8.1)
|
209
|
+
minima (2.5.1)
|
210
|
+
jekyll (>= 3.5, < 5.0)
|
211
|
+
jekyll-feed (~> 0.9)
|
212
|
+
jekyll-seo-tag (~> 2.1)
|
213
|
+
minitest (5.18.0)
|
214
|
+
nokogiri (1.14.2)
|
215
|
+
mini_portile2 (~> 2.8.0)
|
216
|
+
racc (~> 1.4)
|
217
|
+
octokit (4.25.1)
|
218
|
+
faraday (>= 1, < 3)
|
219
|
+
sawyer (~> 0.9)
|
220
|
+
pathutil (0.16.2)
|
221
|
+
forwardable-extended (~> 2.6)
|
222
|
+
public_suffix (4.0.7)
|
223
|
+
racc (1.6.2)
|
224
|
+
rb-fsevent (0.11.2)
|
225
|
+
rb-inotify (0.10.1)
|
226
|
+
ffi (~> 1.0)
|
227
|
+
rexml (3.2.5)
|
228
|
+
rouge (3.26.0)
|
229
|
+
ruby2_keywords (0.0.5)
|
230
|
+
rubyzip (2.3.2)
|
231
|
+
safe_yaml (1.0.5)
|
232
|
+
sass (3.7.4)
|
233
|
+
sass-listen (~> 4.0.0)
|
234
|
+
sass-listen (4.0.0)
|
235
|
+
rb-fsevent (~> 0.9, >= 0.9.4)
|
236
|
+
rb-inotify (~> 0.9, >= 0.9.7)
|
237
|
+
sawyer (0.9.2)
|
238
|
+
addressable (>= 2.3.5)
|
239
|
+
faraday (>= 0.17.3, < 3)
|
240
|
+
simpleidn (0.2.1)
|
241
|
+
unf (~> 0.1.4)
|
242
|
+
terminal-table (1.8.0)
|
243
|
+
unicode-display_width (~> 1.1, >= 1.1.1)
|
244
|
+
typhoeus (1.4.0)
|
245
|
+
ethon (>= 0.9.0)
|
246
|
+
tzinfo (2.0.6)
|
247
|
+
concurrent-ruby (~> 1.0)
|
248
|
+
unf (0.1.4)
|
249
|
+
unf_ext
|
250
|
+
unf_ext (0.0.8.2)
|
251
|
+
unicode-display_width (1.8.0)
|
252
|
+
webrick (1.7.0)
|
253
|
+
yard (0.9.28)
|
254
|
+
webrick (~> 1.7.0)
|
255
|
+
|
256
|
+
PLATFORMS
|
257
|
+
ruby
|
258
|
+
|
259
|
+
DEPENDENCIES
|
260
|
+
github-pages
|
261
|
+
yard
|
262
|
+
|
263
|
+
BUNDLED WITH
|
264
|
+
2.2.33
|
data/docs/_config.yml
ADDED
@@ -0,0 +1,17 @@
|
|
1
|
+
title: Rails REST Framework
|
2
|
+
email: schmitgreg@gmail.com
|
3
|
+
description: Rails REST Framework helps you build awesome Web APIs in Ruby on Rails.
|
4
|
+
url: "https://rails-rest-framework.com"
|
5
|
+
collections:
|
6
|
+
guide:
|
7
|
+
output: true
|
8
|
+
permalink: /:collection/:slug/
|
9
|
+
|
10
|
+
# Build settings
|
11
|
+
markdown: kramdown
|
12
|
+
|
13
|
+
defaults:
|
14
|
+
- scope:
|
15
|
+
path: "" # All files.
|
16
|
+
values:
|
17
|
+
layout: default
|
@@ -0,0 +1,110 @@
|
|
1
|
+
---
|
2
|
+
layout: default
|
3
|
+
title: Routers
|
4
|
+
position: 1
|
5
|
+
slug: routers
|
6
|
+
---
|
7
|
+
# Routers
|
8
|
+
|
9
|
+
You can route RESTful controllers with the normal utilities that Rails provides. However, the REST
|
10
|
+
framework also provides some helpers to route controllers using attributes of the controllers
|
11
|
+
themselves.
|
12
|
+
|
13
|
+
## Routing the API Root
|
14
|
+
|
15
|
+
Your API root should probably have some content describing how one can authenticate with the API,
|
16
|
+
and what sub-controllers exist in the API. The API root can also be a great place to put singleton
|
17
|
+
actions on your API, if needed.
|
18
|
+
|
19
|
+
There are two common ways for an API root to be implemented.
|
20
|
+
|
21
|
+
### Inherited API Root
|
22
|
+
|
23
|
+
You likely have an API controller that your other controllers inherit from, like this:
|
24
|
+
|
25
|
+
```shell
|
26
|
+
app/controllers/
|
27
|
+
├── api
|
28
|
+
│ ├── groups_controller.rb
|
29
|
+
│ ├── movies_controller.rb
|
30
|
+
│ ├── marbles_controller.rb
|
31
|
+
│ └── users_controller.rb
|
32
|
+
├── api_controller.rb
|
33
|
+
└── application_controller.rb
|
34
|
+
```
|
35
|
+
|
36
|
+
If your controllers in the `api` directory inherit from `ApiController` and you want root actions on
|
37
|
+
`ApiController`, then you would setup your root route in the top-level namespace, like this:
|
38
|
+
|
39
|
+
```ruby
|
40
|
+
Rails.application.routes.draw do
|
41
|
+
rest_root :api
|
42
|
+
namespace :api do
|
43
|
+
...
|
44
|
+
end
|
45
|
+
end
|
46
|
+
```
|
47
|
+
|
48
|
+
However, note that actions defined on `ApiController` are defined on all sub-controllers, so if
|
49
|
+
you're using `match` rules to route controllers, then this may lead to undesired behavior.
|
50
|
+
|
51
|
+
### Dedicated API Root
|
52
|
+
|
53
|
+
A better way might be to dedicate a controller for the API root, which would prevent actions and
|
54
|
+
properties defined on the root API from propagating to the rest of the namespace through
|
55
|
+
inheritance. You would add a `RootController` so your directory would look like this:
|
56
|
+
|
57
|
+
```shell
|
58
|
+
app/controllers/
|
59
|
+
├── api
|
60
|
+
│ ├── groups_controller.rb
|
61
|
+
│ ├── movies_controller.rb
|
62
|
+
│ ├── root_controller.rb
|
63
|
+
│ ├── marbles_controller.rb
|
64
|
+
│ └── users_controller.rb
|
65
|
+
├── api_controller.rb
|
66
|
+
└── application_controller.rb
|
67
|
+
```
|
68
|
+
|
69
|
+
Now you can route the root in the `:api` namespace, like this:
|
70
|
+
|
71
|
+
```ruby
|
72
|
+
Rails.application.routes.draw do
|
73
|
+
namespace :api do
|
74
|
+
rest_root # By default this will find and route `Api::RootController`.
|
75
|
+
...
|
76
|
+
end
|
77
|
+
end
|
78
|
+
```
|
79
|
+
|
80
|
+
## Resourceful Routing
|
81
|
+
|
82
|
+
The REST Framework provides resourceful routers `rest_resource` and `rest_resources`, analogous to
|
83
|
+
Rails' `resource` and `resources`. These routers will inspect their corresponding controllers and
|
84
|
+
route `extra_actions` (aliased with `extra_collection_actions`) and `extra_member_actions`
|
85
|
+
automatically.
|
86
|
+
|
87
|
+
```ruby
|
88
|
+
Rails.application.routes.draw do
|
89
|
+
namespace :api do
|
90
|
+
rest_root
|
91
|
+
rest_resource :user
|
92
|
+
rest_resources :movies
|
93
|
+
end
|
94
|
+
end
|
95
|
+
```
|
96
|
+
|
97
|
+
## Non-resourceful Routing
|
98
|
+
|
99
|
+
The `rest_route` non-resourceful router does not route the standard resource routes (`index`,
|
100
|
+
`create`, `show`, `list`, `update`, `delete`). Any actions must be defined as `extra_actions` on the
|
101
|
+
controller.
|
102
|
+
|
103
|
+
```ruby
|
104
|
+
Rails.application.routes.draw do
|
105
|
+
namespace :api do
|
106
|
+
rest_root
|
107
|
+
rest_route :network
|
108
|
+
end
|
109
|
+
end
|
110
|
+
```
|
@@ -0,0 +1,293 @@
|
|
1
|
+
---
|
2
|
+
layout: default
|
3
|
+
title: Controller Mixins
|
4
|
+
position: 2
|
5
|
+
slug: controller-mixins
|
6
|
+
---
|
7
|
+
# Controller Mixins
|
8
|
+
|
9
|
+
This is the core of the REST Framework. Generally speaking, projects already have an existing
|
10
|
+
controller inheritance hierarchy, so we want developers to be able to maintain that project
|
11
|
+
structure while leveraging the power of the REST Framework. Also, different controllers which
|
12
|
+
inherit from the same parent often need different REST Framework mixins. For these reasons, REST
|
13
|
+
Framework provides the controller functionality as modules that you mix into your controllers.
|
14
|
+
|
15
|
+
## Response Rendering
|
16
|
+
|
17
|
+
Before we go into the various controller mixins, one of the core capabilities of the REST Framework
|
18
|
+
is to provide system-consumable responses along side a browsable API for developers. While you can
|
19
|
+
use Rails' builtin rendering tools, such as `render`, the REST Framework provides a rendering helper
|
20
|
+
called `api_response`. This helper allows you to return a browsable API response for the `html`
|
21
|
+
format which shows you what the JSON/XML response would look like, along with faster and lighter
|
22
|
+
responses for `json` and `xml` formats.
|
23
|
+
|
24
|
+
Here is an example:
|
25
|
+
|
26
|
+
```ruby
|
27
|
+
class ApiController < ApplicationController
|
28
|
+
include RESTFramework::BaseControllerMixin
|
29
|
+
self.extra_actions = {test: :get}
|
30
|
+
|
31
|
+
def test
|
32
|
+
api_response({message: "Test successful!"})
|
33
|
+
end
|
34
|
+
end
|
35
|
+
```
|
36
|
+
|
37
|
+
## `BaseControllerMixin`
|
38
|
+
|
39
|
+
To transform a controller into the simplest possible RESTful controller, you can include
|
40
|
+
`BaseControllerMixin`, which provides a simple `root` action so it can be used at the API root.
|
41
|
+
|
42
|
+
```ruby
|
43
|
+
class ApiController < ApplicationController
|
44
|
+
include RESTFramework::BaseControllerMixin
|
45
|
+
end
|
46
|
+
```
|
47
|
+
|
48
|
+
### Controller Attributes
|
49
|
+
|
50
|
+
You can customize the behavior of `BaseControllerMixin` by setting or mutating various class
|
51
|
+
attributes.
|
52
|
+
|
53
|
+
#### `singleton_controller`
|
54
|
+
|
55
|
+
This property primarily controls the routes that are generated for a RESTful controller. If you use
|
56
|
+
`api_resource`/`api_resources` to define whether the generates routes are for a collection or for
|
57
|
+
a single member, then you do not need to use this property. However, if you are autogenerating those
|
58
|
+
routers, then `singleton_controller` will tell REST Framework whether to provide collection routes
|
59
|
+
(when `singleton_controller` is falsy) or member routes (when `singleton_controller` is truthy). To
|
60
|
+
read more about singular vs plural routing, see Rails' documentation here:
|
61
|
+
https://guides.rubyonrails.org/routing.html#singular-resources.
|
62
|
+
|
63
|
+
#### `extra_actions`
|
64
|
+
|
65
|
+
This property defines extra actions on the controller to be routed. It is a hash of
|
66
|
+
`endpoint -> method(s)` (where `method(s)` can be a method symbol or an array of method symbols).
|
67
|
+
|
68
|
+
```ruby
|
69
|
+
class ApiController < ApplicationController
|
70
|
+
include RESTFramework::BaseControllerMixin
|
71
|
+
self.extra_actions = {test: :get}
|
72
|
+
|
73
|
+
def test
|
74
|
+
api_response({message: "Test successful!"})
|
75
|
+
end
|
76
|
+
end
|
77
|
+
```
|
78
|
+
|
79
|
+
Or with multiple methods:
|
80
|
+
|
81
|
+
```ruby
|
82
|
+
class ApiController < ApplicationController
|
83
|
+
include RESTFramework::BaseControllerMixin
|
84
|
+
self.extra_actions = {test: [:get, :post]}
|
85
|
+
|
86
|
+
def test
|
87
|
+
api_response({message: "Test successful!"})
|
88
|
+
end
|
89
|
+
end
|
90
|
+
```
|
91
|
+
|
92
|
+
If your action conflicts with a builtin method, then you can also override the path:
|
93
|
+
|
94
|
+
```ruby
|
95
|
+
class ApiController < ApplicationController
|
96
|
+
include RESTFramework::BaseControllerMixin
|
97
|
+
|
98
|
+
# This will route `test_action` to `/test`, in case there is already a `test` method that cannot
|
99
|
+
# be overridden.
|
100
|
+
self.extra_actions = {test_action: {path: :test, methods: :get}}
|
101
|
+
|
102
|
+
def test_action
|
103
|
+
api_response({message: "Test successful!"})
|
104
|
+
end
|
105
|
+
end
|
106
|
+
```
|
107
|
+
|
108
|
+
## `ModelControllerMixin`
|
109
|
+
|
110
|
+
`ModelControllerMixin` assists with providing the standard model CRUD (create, read, update,
|
111
|
+
destroy) for your controller. This is the most commonly used mixin since it provides default
|
112
|
+
behavior for models which matches Rails' default routing.
|
113
|
+
|
114
|
+
```ruby
|
115
|
+
class Api::MoviesController < ApiController
|
116
|
+
include RESTFramework::ModelControllerMixin
|
117
|
+
end
|
118
|
+
```
|
119
|
+
|
120
|
+
By default, all columns and associations are included in `self.fields`, which can be helpful when
|
121
|
+
developing an administrative API. For user-facing APIs, however, `self.fields` should always be
|
122
|
+
explicitly defined.
|
123
|
+
|
124
|
+
### Controller Attributes
|
125
|
+
|
126
|
+
You can customize the behavior of `ModelControllerMixin` by setting or mutating various class
|
127
|
+
attributes.
|
128
|
+
|
129
|
+
#### `model`
|
130
|
+
|
131
|
+
The `model` property allows you to define the model if it is not obvious from the controller name.
|
132
|
+
|
133
|
+
```ruby
|
134
|
+
class Api::CoolMoviesController < ApiController
|
135
|
+
include RESTFramework::ModelControllerMixin
|
136
|
+
|
137
|
+
self.model = Movie
|
138
|
+
end
|
139
|
+
```
|
140
|
+
|
141
|
+
#### `recordset`
|
142
|
+
|
143
|
+
The `recordset` property allows you to define the set of records this API should be limited to. If
|
144
|
+
you need to change the recordset based on properties of the request, then you can override the
|
145
|
+
`get_recordset()` method.
|
146
|
+
|
147
|
+
```ruby
|
148
|
+
class Api::CoolMoviesController < ApiController
|
149
|
+
include RESTFramework::ModelControllerMixin
|
150
|
+
|
151
|
+
self.recordset = Movie.where(cool: true).order({id: :asc})
|
152
|
+
end
|
153
|
+
```
|
154
|
+
|
155
|
+
#### `extra_member_actions`
|
156
|
+
|
157
|
+
The `extra_member_actions` property allows you to define additional actions on individual records.
|
158
|
+
|
159
|
+
```ruby
|
160
|
+
class Api::MoviesController < ApiController
|
161
|
+
include RESTFramework::ModelControllerMixin
|
162
|
+
|
163
|
+
self.extra_member_actions = {disable: :post}
|
164
|
+
|
165
|
+
def disable
|
166
|
+
@record = self.get_record # REST Framework will rescue ActiveRecord::RecordNotFound
|
167
|
+
|
168
|
+
# REST Framework will rescue ActiveRecord::RecordInvalid or ActiveRecord::RecordNotSaved
|
169
|
+
@record.update!(enabled: false)
|
170
|
+
|
171
|
+
return api_response(@record)
|
172
|
+
end
|
173
|
+
end
|
174
|
+
```
|
175
|
+
|
176
|
+
#### `fields`
|
177
|
+
|
178
|
+
The `fields` property defines the default fields for serialization and for parameters allowed from
|
179
|
+
the body or query string.
|
180
|
+
|
181
|
+
```ruby
|
182
|
+
class Api::MoviesController < ApiController
|
183
|
+
include RESTFramework::ModelControllerMixin
|
184
|
+
|
185
|
+
self.fields = [:id, :name]
|
186
|
+
end
|
187
|
+
```
|
188
|
+
|
189
|
+
#### `action_fields`
|
190
|
+
|
191
|
+
The `action_fields` property is similar to `fields`, but allows you to define different fields for
|
192
|
+
different actions. A good example is to serialize expensive computed properties only in the `show`
|
193
|
+
action, but not in the `list` action (where many records are serialized).
|
194
|
+
|
195
|
+
```ruby
|
196
|
+
class Api::MoviesController < ApiController
|
197
|
+
include RESTFramework::ModelControllerMixin
|
198
|
+
|
199
|
+
self.fields = [:id, :name]
|
200
|
+
self.action_fields = {
|
201
|
+
show: [:id, :name, :some_expensive_computed_property],
|
202
|
+
}
|
203
|
+
end
|
204
|
+
```
|
205
|
+
|
206
|
+
#### `native_serializer_config`
|
207
|
+
|
208
|
+
These properties define the serializer configuration if you are using the native `ActiveModel`
|
209
|
+
serializer. You can also specify serializers for singular/plural
|
210
|
+
|
211
|
+
```ruby
|
212
|
+
class Api::MoviesController < ApiController
|
213
|
+
include RESTFramework::ModelControllerMixin
|
214
|
+
|
215
|
+
self.native_serializer_config = {
|
216
|
+
only: [:id, :name],
|
217
|
+
methods: [:active, :some_expensive_computed_property],
|
218
|
+
include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
|
219
|
+
}
|
220
|
+
|
221
|
+
# Or you could configure a default and a plural serializer:
|
222
|
+
self.native_serializer_plural_config = {
|
223
|
+
only: [:id, :name],
|
224
|
+
methods: [:active],
|
225
|
+
include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
|
226
|
+
}
|
227
|
+
self.native_serializer_config = {
|
228
|
+
only: [:id, :name],
|
229
|
+
methods: [:active, :some_expensive_computed_property],
|
230
|
+
include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
|
231
|
+
}
|
232
|
+
|
233
|
+
# Or you could configure a default and a singular serializer:
|
234
|
+
self.native_serializer_config = {
|
235
|
+
only: [:id, :name],
|
236
|
+
methods: [:active],
|
237
|
+
include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
|
238
|
+
}
|
239
|
+
self.native_serializer_singular_config = {
|
240
|
+
only: [:id, :name],
|
241
|
+
methods: [:active, :some_expensive_computed_property],
|
242
|
+
include: {cast_members: { only: [:id, :name], methods: [:net_worth] }},
|
243
|
+
}
|
244
|
+
end
|
245
|
+
```
|
246
|
+
|
247
|
+
#### `allowed_parameters` / `allowed_action_parameters`
|
248
|
+
|
249
|
+
These properties define the permitted parameters to be used in the request body for create/update
|
250
|
+
actions. If you need different allowed parameters, then you can also override the
|
251
|
+
`get_create_params` or `get_update_params` methods.
|
252
|
+
|
253
|
+
```ruby
|
254
|
+
class Api::MoviesController < ApiController
|
255
|
+
include RESTFramework::ModelControllerMixin
|
256
|
+
|
257
|
+
self.allowed_parameters = [:name]
|
258
|
+
end
|
259
|
+
```
|
260
|
+
|
261
|
+
#### `create_from_recordset` (default: `true`)
|
262
|
+
|
263
|
+
The `create_from_recordset` attribute (`true` by default) is a boolean to control the behavior in
|
264
|
+
the `create` action. If it is disabled, records will not be created from the filtered recordset, but
|
265
|
+
rather will be created directly from the model interface.
|
266
|
+
|
267
|
+
For example, if this is your controller:
|
268
|
+
|
269
|
+
```ruby
|
270
|
+
class Api::CoolMoviesController < ApiController
|
271
|
+
include RESTFramework::ModelControllerMixin
|
272
|
+
|
273
|
+
def get_recordset
|
274
|
+
return Movie.where(cool: true)
|
275
|
+
end
|
276
|
+
end
|
277
|
+
```
|
278
|
+
|
279
|
+
Then if you hit the `create` action with the payload `{name: "Superman"}`, it will also set `cool`
|
280
|
+
to `true` on the new record, because that property is inherited from the recordset.
|
281
|
+
|
282
|
+
## `ReadOnlyModelControllerMixin`
|
283
|
+
|
284
|
+
`ReadOnlyModelControllerMixin` only enables list/show actions. In this example, since we're naming
|
285
|
+
this controller in a way that doesn't make the model obvious, we can set that explicitly:
|
286
|
+
|
287
|
+
```ruby
|
288
|
+
class Api::ReadOnlyMoviesController < ApiController
|
289
|
+
include RESTFramework::ReadOnlyModelControllerMixin
|
290
|
+
|
291
|
+
self.model = Movie
|
292
|
+
end
|
293
|
+
```
|