parameters_schema 1.0.1 → 1.0.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile +2 -1
- data/README.md +57 -20
- data/lib/parameters_schema/core_ext.rb +0 -1
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 14b2e93c33b07b2beb454f9b604f4f77e96da0e6
|
4
|
+
data.tar.gz: 64bb0eaf552948ddb687625ece733d4f8a08fe38
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: a2eb862ee2b536e377f0177b70ca983f6b618fab0222fe89bf423ae4228eef6f5db87e4d8cde5defec8814d7a5180e6997198abe0ed016b0b3037573ff5ccdbc
|
7
|
+
data.tar.gz: 269810eec92651bbd6701a9df474cbd394b87a1428f2e417091aef4896ddc409d8baf1f9a5c05096901e821441564667ad540475679a67e73c09657dead4e605
|
data/Gemfile
CHANGED
data/README.md
CHANGED
@@ -1,10 +1,8 @@
|
|
1
1
|
# Parameters Schema
|
2
2
|
|
3
|
-
|
3
|
+
This gem is an alternative to **[strong_parameters](https://github.com/rails/strong_parameters)** to validate data at the controller level.
|
4
4
|
|
5
|
-
|
6
|
-
|
7
|
-
For example, let's say you want your operation `create` to require a `Fixnum` parameter between 1 and 99. With strong_parameters, you're out of luck. With this gem, you simply write in your controller:
|
5
|
+
For example, let's say you want your operation `create` to require a `Fixnum` parameter between `1` and `99`:
|
8
6
|
``` ruby
|
9
7
|
class Api::PeopleController < Api::BaseController
|
10
8
|
def create
|
@@ -12,7 +10,7 @@ class Api::PeopleController < Api::BaseController
|
|
12
10
|
param :age, type: Fixnum, allow: (1..99)
|
13
11
|
end
|
14
12
|
|
15
|
-
|
13
|
+
@person = Person.create!(validated_params)
|
16
14
|
end
|
17
15
|
end
|
18
16
|
```
|
@@ -20,30 +18,57 @@ end
|
|
20
18
|
So when you use this controller:
|
21
19
|
``` ruby
|
22
20
|
> app.post 'api/people', age: 12 # validated_params = { age: 12 }
|
23
|
-
> app.post 'api/people', age: 100 # throws a ParameterSchema::InvalidParameters
|
21
|
+
> app.post 'api/people', age: 100 # throws a ParameterSchema::InvalidParameters
|
24
22
|
```
|
25
23
|
|
26
|
-
## Why use this gem instead of strong_parameters
|
24
|
+
## Why use this gem instead of *strong_parameters*:
|
27
25
|
|
28
|
-
* You
|
29
|
-
* You want
|
30
|
-
* You
|
26
|
+
* You want more control over the parameters of your API, at the *type* and *format* level.
|
27
|
+
* You want a strict API that will only accept well-formed requests.
|
28
|
+
* You don't grasp the *strong_parameters* syntax and wants something more like a DSL.
|
29
|
+
* You want to validate data outside of Rails.
|
31
30
|
|
32
31
|
## Installation
|
33
32
|
|
34
|
-
Add in your Gemfile
|
33
|
+
Add in your `Gemfile`:
|
35
34
|
``` ruby
|
36
35
|
gem 'parameters_schema'
|
37
36
|
```
|
38
37
|
|
39
|
-
Add in your project:
|
38
|
+
Add in your project (not required for Rails):
|
40
39
|
``` ruby
|
41
40
|
require 'parameters_schema'
|
42
41
|
```
|
43
42
|
|
43
|
+
## Quick start
|
44
|
+
|
45
|
+
Read this then _Integrate with Rails_ if you want to use this gem quickly.
|
46
|
+
|
47
|
+
Let's take the example at the beginning of this README, with more details:
|
48
|
+
|
49
|
+
``` ruby
|
50
|
+
class Api::PeopleController < Api::BaseController
|
51
|
+
def create
|
52
|
+
# 1. For each request, you define a schema (i.e. the parameters of the request).
|
53
|
+
schema = ParametersSchema::Schema.new do
|
54
|
+
param :age, type: Fixnum, allow: (1..99)
|
55
|
+
end
|
56
|
+
|
57
|
+
# 2. When a user makes a request, you validate it against the schema.
|
58
|
+
# - When the request is invalid, an exception is raised.
|
59
|
+
# - When the request is valid, you receive a sanitized hash.
|
60
|
+
validated_params = schema.validate!(params)
|
61
|
+
|
62
|
+
@person = Person.create!(validated_params)
|
63
|
+
end
|
64
|
+
end
|
65
|
+
```
|
66
|
+
|
67
|
+
Now, _Integrate with Rails_ gives pointers on how to simplify all this.
|
68
|
+
|
44
69
|
## Schema
|
45
70
|
|
46
|
-
The schema is the heart of this gem.
|
71
|
+
The schema is the heart of this gem. With a simple DSL, you define the parameters of a request.
|
47
72
|
|
48
73
|
Creating a schema:
|
49
74
|
``` ruby
|
@@ -52,16 +77,18 @@ schema = ParametersSchema::Schema.new do
|
|
52
77
|
# ... but an empty schema is also valid.
|
53
78
|
end
|
54
79
|
```
|
80
|
+
|
55
81
|
Validating parameters against a schema:
|
56
82
|
``` ruby
|
57
83
|
params = { potatoe: 'Eramosa' }
|
58
|
-
schema.validate!(params)
|
84
|
+
schema.validate!(params)
|
59
85
|
```
|
60
86
|
|
61
87
|
The minimal representation of a parameter is:
|
62
88
|
``` ruby
|
63
89
|
param :potatoe
|
64
90
|
```
|
91
|
+
|
65
92
|
This represents a `required` parameter of type `String` accepting any characters and which doesn't allow nil or empty values.
|
66
93
|
|
67
94
|
The valid options for a parameter are:
|
@@ -75,7 +102,7 @@ The valid options for a parameter are:
|
|
75
102
|
|
76
103
|
### Parameter types
|
77
104
|
|
78
|
-
The available types are:
|
105
|
+
The available types are:
|
79
106
|
``` ruby
|
80
107
|
* String
|
81
108
|
* Symbol
|
@@ -137,9 +164,9 @@ end
|
|
137
164
|
|
138
165
|
### The `allow` and `deny` options
|
139
166
|
|
140
|
-
By default, the value of a parameter can be any one in the spectrum of a type, with the exception of nil and empty. The `allow` and `deny` options can be used to further refine the accepted values.
|
167
|
+
By default, the value of a parameter can be any one in the spectrum of a type, with the exception of `nil` and empty. The `allow` and `deny` options can be used to further refine the accepted values.
|
141
168
|
|
142
|
-
To accept nil or empty values:
|
169
|
+
To accept `nil` or empty values:
|
143
170
|
``` ruby
|
144
171
|
param :potatoe, allow: :nil
|
145
172
|
# => accepts nil, 'Kennebec' but not ''.
|
@@ -150,7 +177,7 @@ param :potatoe, allow: :empty
|
|
150
177
|
param :potatoe, allow: [:nil, :empty]
|
151
178
|
# => accepts nil, '' and 'Kennebec'
|
152
179
|
```
|
153
|
-
Of course, this
|
180
|
+
Of course, this `nil` or `empty` restriction doesn't make sense for all the types so it will only be applied when it does.
|
154
181
|
|
155
182
|
To accept predefined values:
|
156
183
|
``` ruby
|
@@ -220,12 +247,13 @@ The possible error codes are (in the order the are validated):
|
|
220
247
|
|
221
248
|
## Integrate with Rails
|
222
249
|
|
223
|
-
This gem can be used outside of Rails but was created with Rails in mind. For example, the parameters `controller
|
250
|
+
This gem can be used outside of Rails but was created with Rails in mind. For example, the parameters `controller`, `action` and `format` are skipped by default (see Options section to override this behavior) and the parameters are defined in a `Hash`. However, this gem doesn't insinuate itself in your project so you must manually add it in your controllers or anywhere else that make sense to you. Here is a little recipe to add validation in your API pipeline:
|
224
251
|
|
225
252
|
In the base controller of your API, add this **helper**:
|
226
253
|
``` ruby
|
227
254
|
# Validate the parameters of an action, using a schema.
|
228
255
|
# Returns the validated parameters and throw exceptions on invalid input.
|
256
|
+
# Note: this helper could be refined to cache the schemas.
|
229
257
|
def validate_params(¶meters_schema)
|
230
258
|
schema = ParametersSchema::Schema.new(¶meters_schema)
|
231
259
|
schema.validate!(params)
|
@@ -274,10 +302,19 @@ Available options:
|
|
274
302
|
|
275
303
|
Yes, please. Bug fixes, new features, refactoring, unit tests. Send your precious pull requests.
|
276
304
|
|
305
|
+
### Developing this gem
|
306
|
+
|
307
|
+
1. Fork this repository.
|
308
|
+
2. Clone your fork.
|
309
|
+
3. (Optional) Prepare it with `rbenv` or `RVM`. Ex: `echo 2.3.0 > .ruby-version`.
|
310
|
+
4. `bundle install` to install the gems.
|
311
|
+
5. `rake test` to launch the tests suite.
|
312
|
+
6. Make your changes and send me pull requests.
|
313
|
+
|
277
314
|
### Ideas
|
278
315
|
|
279
316
|
* Array of arrays of ...
|
280
|
-
*
|
317
|
+
* `min` and `max` options for numeric values (instead of `allow: (min..max)`)
|
281
318
|
* More `allow` options
|
282
319
|
* Better refine error codes
|
283
320
|
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: parameters_schema
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
4
|
+
version: 1.0.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Jodi Giordano
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2016-02-24 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: activesupport
|
@@ -69,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
69
69
|
version: '0'
|
70
70
|
requirements: []
|
71
71
|
rubyforge_project:
|
72
|
-
rubygems_version: 2.
|
72
|
+
rubygems_version: 2.5.1
|
73
73
|
signing_key:
|
74
74
|
specification_version: 4
|
75
75
|
summary: Strict schema for request parameters
|