snorlax 0.1.1 → 0.1.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +215 -17
- data/app/controllers/snorlax/base.rb +6 -2
- data/lib/snorlax/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: c17a98c1013d790464bb3a26a6664777e239eafc
|
4
|
+
data.tar.gz: 528dfab11bd3262d06c38c7e95cdaadfba38c20a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 98972fe7c64a5f419fcc36b53624e1c8d537a54a2f24f4185fd82c6ece568a5767fd2b1ddf48274e6fbe00f15bc668b73eb9d85a3f4ea17e8f303f7d0b2ba85a
|
7
|
+
data.tar.gz: 25af62fda64ddd54c860d6e0e63739cfe6e45618d1e7a510833b28cf6db6e47df26fce7b8044ba44c8a6e96bb865d593c71b99862291fead0c36ebe361b67414
|
data/README.md
CHANGED
@@ -41,26 +41,224 @@ end
|
|
41
41
|
|
42
42
|
Once you've got it installed, you're good to go!
|
43
43
|
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
44
|
+
#### Some things to know about Snorlax:
|
45
|
+
|
46
|
+
Snorlax is designed to provide a set of flexible API endpoints for client side consumption. It uses side loading, which means that all of the records returned are unnested and easily available for consumption.
|
47
|
+
|
48
|
+
#### The show action
|
49
|
+
|
50
|
+
By default, Snorlax will fetch the requested model by `id` using the `ActiveModel::Base.find` method. To override this behaviour, you may override the `load_resource` method in your controller.
|
51
|
+
|
52
|
+
```
|
53
|
+
class TaurosController < Snorlax::Base
|
54
|
+
def load_resource
|
55
|
+
SafariZone.find(params[:id])
|
56
|
+
end
|
57
|
+
end
|
58
|
+
```
|
59
|
+
|
60
|
+
NB: This would be a great place to ensure that the current user is allowed to view the requested resource.
|
61
|
+
|
62
|
+
#### The index action
|
63
|
+
|
64
|
+
Snorlax DEMANDS that you define two separate methods for the index action to work properly:
|
65
|
+
- `public_records` - records which are available publicly (ie, they can be viewed even if current_user is nil)
|
66
|
+
- `visible_records` - records which the current user is allowed to access.
|
67
|
+
|
68
|
+
```
|
69
|
+
class StaryusController < Snorlax::Base
|
70
|
+
def public_records
|
71
|
+
Staryu.visible_to_public
|
72
|
+
end
|
73
|
+
|
74
|
+
def visible_records
|
75
|
+
current_user.staryus
|
76
|
+
end
|
77
|
+
end
|
78
|
+
```
|
79
|
+
If these are the same, you may override the `accessible_records` method instead
|
80
|
+
|
81
|
+
```
|
82
|
+
class StarmiesController < Snorlax::Base
|
83
|
+
def accessible_records
|
84
|
+
Starmie.all
|
85
|
+
end
|
86
|
+
end
|
87
|
+
```
|
88
|
+
|
89
|
+
The default index action look like this:
|
90
|
+
|
91
|
+
```
|
92
|
+
def index
|
93
|
+
instantiate_collection
|
94
|
+
respond_with_collection
|
95
|
+
end
|
96
|
+
```
|
97
|
+
|
98
|
+
but there are many options to customize it.
|
99
|
+
|
100
|
+
##### Paging the index action
|
101
|
+
|
102
|
+
A Snorlax controller can accept `from` and `per` parameters for paging. For example,
|
103
|
+
|
104
|
+
```
|
105
|
+
/api/vi/psyducks?from=0&per=100
|
106
|
+
```
|
107
|
+
|
108
|
+
will return the first 100 psyducks within the accessible records.
|
109
|
+
|
110
|
+
If no `from` or `per` params are provided, Snorlax will default to the first 50 records. (from = 0, per = 50)
|
111
|
+
|
112
|
+
You can override the default page size by overriding the `default_page_size` method.
|
113
|
+
|
114
|
+
```
|
115
|
+
class WobbuffetsController < Snorlax::Base
|
116
|
+
def default_page_size
|
117
|
+
25
|
118
|
+
end
|
119
|
+
end
|
120
|
+
```
|
121
|
+
|
122
|
+
##### Timeframing the index action
|
123
|
+
|
124
|
+
A Snorlax controller can accept `since` and `until` parameters for timeframing. The date it looks for defaults to `created_at`. For example,
|
125
|
+
|
126
|
+
```
|
127
|
+
/api/v1/charmanders?since=11-11-2011&until=12-12-2012
|
128
|
+
```
|
129
|
+
|
130
|
+
will return charmanders which were created between Nov 11, 2011, and Dec 12, 2012.
|
131
|
+
|
132
|
+
You can override the datetime column the query looks at by passing the `timeframe_for` option. For example,
|
133
|
+
|
134
|
+
```
|
135
|
+
/api/v1/charmeleons?since=11-11-2011&until=12-12-2012&timeframe_for=evolved_at
|
136
|
+
```
|
137
|
+
|
138
|
+
will return charmeleons which evolved between Nov 11, 2011, and Dec 12, 2012
|
139
|
+
|
140
|
+
Since and until can be in any format that `Date.parse` will accept.
|
141
|
+
|
142
|
+
##### Overriding the timeframing or pagination options
|
143
|
+
|
144
|
+
If you want to disallow timeframing and/or pagination for a particular action, simple pass `timeframe_collection: false` or `page_collection: false` when the collection is instantiated.
|
145
|
+
|
146
|
+
```
|
147
|
+
class SquirtlesController < Snorlax::Base
|
148
|
+
def all_squirtles
|
149
|
+
instantiate_collection paginate_collection: false, timeframe_collection: false
|
150
|
+
respond_with_collection
|
151
|
+
end
|
152
|
+
end
|
153
|
+
```
|
154
|
+
|
155
|
+
##### Custom filtering on the index action
|
156
|
+
|
157
|
+
Snorlax also provides a dead simple way to provide your own filters, in addition to and in combination with the ones provided.
|
158
|
+
You can do this by passing a block to the `instantiate_collection` method in your controller action. For example,
|
159
|
+
|
160
|
+
```
|
161
|
+
class ChanseysController < Snorlax::Base
|
162
|
+
def sleeping
|
163
|
+
instantiate_collection { |collection| collection.where(sleeping: true) }
|
164
|
+
respond_with_collection
|
165
|
+
end
|
166
|
+
end
|
167
|
+
```
|
168
|
+
|
169
|
+
Will return all sleeping Chanseys. (This can be combined with timeframing and paginating as well.)
|
170
|
+
(NB: this filtering happens before the collection is paginated or timeframed, so it's a good opportunity to add additional filters
|
171
|
+
or apply an order to your records. Or both!)
|
172
|
+
|
173
|
+
##### Customizing the serializer options
|
174
|
+
|
175
|
+
By default, Snorlax will find a serializer based on the controller name, and serialize out your collection of records with a root.
|
176
|
+
|
177
|
+
##### To override serializer and root for all actions in the controller
|
178
|
+
|
179
|
+
You can override the serializer being used or the serializer root across the controller by defining a `resource_serializer` or `serializer_root` method, respectively:
|
180
|
+
```
|
181
|
+
class DittosController < Snorlax::Base
|
182
|
+
def resource_serializer
|
183
|
+
PokemonSerializer
|
184
|
+
end
|
185
|
+
|
186
|
+
def serializer_root
|
187
|
+
:pokemon
|
188
|
+
end
|
189
|
+
end
|
190
|
+
```
|
191
|
+
|
192
|
+
This will result is JSON like this:
|
193
|
+
```
|
194
|
+
{ pokemon: [{ pokemon_serializer_field_a: 'valueA', pokemon_serializer_field_b: 'valueB' }] }
|
195
|
+
```
|
196
|
+
|
197
|
+
##### To override serializer and root for a single action
|
198
|
+
|
199
|
+
To do this for a particular action, pass the `serializer` or `root` option to respond_with_collection.
|
200
|
+
(NB: You can also pass a scope to the serializer in this way, by passing a 'scope' option)
|
201
|
+
|
202
|
+
```
|
203
|
+
class DittosController < Snorlax::Base
|
204
|
+
def index
|
205
|
+
instantiate_collection
|
206
|
+
respond_with_collection serializer: PokemonSerializer, root: :pokemon, scope: { is_ditto: true }
|
207
|
+
end
|
208
|
+
end
|
209
|
+
```
|
210
|
+
|
211
|
+
#### The create / update actions
|
212
|
+
|
213
|
+
By default, Snorlax will load the requested resource, perform an action on it, and then respond with the resource (with the same response as the show action) It looks like this:
|
214
|
+
|
215
|
+
```
|
216
|
+
def create
|
217
|
+
instantiate_resource
|
218
|
+
create_action
|
219
|
+
respond_with_resource
|
220
|
+
end
|
221
|
+
|
222
|
+
def create_action
|
223
|
+
resource.save
|
224
|
+
end
|
225
|
+
```
|
226
|
+
|
227
|
+
##### Overriding the action command
|
228
|
+
|
229
|
+
If you have more complicated logic for creating or updating records (your creation / update logic is wrapped up in a service object, for example), simply override the `create_action` method (or the `update_action` method in the case of update)
|
230
|
+
|
231
|
+
```
|
232
|
+
def MewtwosController < Snorlax::Base
|
233
|
+
def create_action
|
234
|
+
Science.faff_about(resource_params)
|
235
|
+
end
|
236
|
+
end
|
237
|
+
```
|
238
|
+
|
239
|
+
(NB: this is a good opportunity to make sure that the current user has permission to modify the record.)
|
240
|
+
|
241
|
+
##### Overriding the resource serialization
|
242
|
+
|
243
|
+
`respond_with_resource` accepts the same parameters as respond_with_collection, to allow for single-action customization of the json response.
|
244
|
+
|
245
|
+
```
|
246
|
+
def MewtwosController < Snorlax::Base
|
247
|
+
def create
|
248
|
+
instantiate_resource
|
249
|
+
create_action
|
250
|
+
respond_with_resource { serializer: LegendarySerializer, root: 'legendary_pokemon' }
|
251
|
+
end
|
252
|
+
end
|
253
|
+
```
|
254
|
+
|
255
|
+
##### If there are errors on the object
|
256
|
+
|
257
|
+
TODO: explain the respond_with_errors behaviour
|
60
258
|
|
61
259
|
## Contributing
|
62
260
|
|
63
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/gdpelican/snorlax. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
|
261
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/gdpelican/snorlax. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
64
262
|
|
65
263
|
## License
|
66
264
|
|
@@ -140,7 +140,7 @@ module Snorlax
|
|
140
140
|
"#{resource_name}_serializer".camelize.constantize
|
141
141
|
end
|
142
142
|
|
143
|
-
def respond_with_resource(scope:
|
143
|
+
def respond_with_resource(scope: default_scope, serializer: resource_serializer, root: serializer_root)
|
144
144
|
if resource.errors.empty?
|
145
145
|
respond_with_collection(resources: [resource], scope: scope, serializer: serializer, root: root)
|
146
146
|
else
|
@@ -148,7 +148,7 @@ module Snorlax
|
|
148
148
|
end
|
149
149
|
end
|
150
150
|
|
151
|
-
def respond_with_collection(resources: collection, scope:
|
151
|
+
def respond_with_collection(resources: collection, scope: default_scope, serializer: resource_serializer, root: serializer_root)
|
152
152
|
render json: resources, scope: scope, each_serializer: serializer, root: root
|
153
153
|
end
|
154
154
|
|
@@ -163,6 +163,10 @@ module Snorlax
|
|
163
163
|
def serializer_root
|
164
164
|
controller_name
|
165
165
|
end
|
166
|
+
|
167
|
+
def default_scope
|
168
|
+
{}
|
169
|
+
end
|
166
170
|
end
|
167
171
|
end
|
168
172
|
|
data/lib/snorlax/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: snorlax
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.1.
|
4
|
+
version: 0.1.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- James Kiesel (gdpelican)
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2015-08-
|
11
|
+
date: 2015-08-18 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: rails
|