rest_framework 0.8.16 → 0.8.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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
+ ```