filterparams 0.9.1 → 0.9.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- metadata +4 -202
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 4d82dc362a305f822045eb821bd97bc969a63f92
|
4
|
+
data.tar.gz: b2d1063e5eae7d3944c5502d91baf0099d6f8722
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 683f2c252435e5d8bb6cf30405326a535b1eff2ca0a5b07b1b7c4f98e8049f939ddbacc1f6a07507320c718e7e973907378f00204b0cb1f0f163386da2dc7407
|
7
|
+
data.tar.gz: 2f4a75c49cf62af306496b5f08769b0297ec1cc0ecaa5db1f7bd86d5db6cdc805daeff9088f69c0db8fdd5012ac16837b38266ba2aa3c731dc72e57692b5fd90
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: filterparams
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.9.
|
4
|
+
version: 0.9.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Christoph Brand
|
@@ -128,207 +128,9 @@ dependencies:
|
|
128
128
|
- - ">="
|
129
129
|
- !ruby/object:Gem::Version
|
130
130
|
version: 1.6.0
|
131
|
-
description:
|
132
|
-
|
133
|
-
|
134
|
-
Filterparams is a library for specifying filters through a REST API
|
135
|
-
on collection resources on top of HTTP. It provides the capability
|
136
|
-
to specify SQL-like syntax on top of query parameters.
|
137
|
-
|
138
|
-
Due to it's intended use of building [JSONAPI](http://jsonapi.org/)
|
139
|
-
libraries with this definition, it is compatible with the definition
|
140
|
-
and encapsulates it's syntax through the prefixed `filter` parameters.
|
141
|
-
|
142
|
-
## Installation ##
|
143
|
-
|
144
|
-
The library is available through the `filterparams` gem on [RubyGems](https://rubygems.org/gems/filterparams)
|
145
|
-
and thus can be installed through the command line or by adding the package to
|
146
|
-
your Gemfile.
|
147
|
-
|
148
|
-
```
|
149
|
-
gem install filterparams
|
150
|
-
```
|
151
|
-
|
152
|
-
## Example ##
|
153
|
-
|
154
|
-
Given the URL (non URL escaped for better readability):
|
155
|
-
|
156
|
-
```
|
157
|
-
/users?filter[param][name][like][no_brand_name]=doe&filter[param][first_name]=doe%&filter[binding]=(!no_brand_name&first_name)&filter[order]=name&filter[order]=desc(first_name)
|
158
|
-
```
|
159
|
-
|
160
|
-
It can be parsed with the following code:
|
161
|
-
|
162
|
-
```ruby
|
163
|
-
require 'uri'
|
164
|
-
require 'cgi'
|
165
|
-
require 'filterparams'
|
166
|
-
|
167
|
-
url = 'http://www.example.com/users?' +
|
168
|
-
'filter[param][name][like][no_brand_name]=doe' +
|
169
|
-
'&filter[param][first_name]=doe%' +
|
170
|
-
'&filter[binding]=%28%21no_brand_name%26first_name%29' +
|
171
|
-
'&filter[order]=name&filter[order]=desc(first_name)'
|
172
|
-
|
173
|
-
data = CGI.parse(URI.parse(url).query)
|
174
|
-
|
175
|
-
Filterparams::extract_query(data)
|
176
|
-
```
|
177
|
-
|
178
|
-
This would result into a query instance being produced with the
|
179
|
-
following data:
|
180
|
-
|
181
|
-
```
|
182
|
-
#<Filterparams::Query:0x007ff78b1a51c8
|
183
|
-
@filters=
|
184
|
-
#<Filterparams::And:0x007ff78b1a57e0
|
185
|
-
@left=
|
186
|
-
#<Filterparams::Not:0x007ff78b1a6ed8
|
187
|
-
@inner=
|
188
|
-
#<Filterparams::Parameter:0x007ff78b1ee940
|
189
|
-
@alias="no_brand_name",
|
190
|
-
@filter="like",
|
191
|
-
@name="name",
|
192
|
-
@value="doe">>,
|
193
|
-
@right=
|
194
|
-
#<Filterparams::Parameter:0x007ff78b1ee918
|
195
|
-
@alias=nil,
|
196
|
-
@filter=nil,
|
197
|
-
@name="first_name",
|
198
|
-
@value="doe%">>,
|
199
|
-
@orders=
|
200
|
-
[#<Filterparams::Order:0x007ff78b1ee5f8 @direction="asc", @name="name">,
|
201
|
-
#<Filterparams::Order:0x007ff78b1ee3a0
|
202
|
-
@direction="desc",
|
203
|
-
@name="first_name">]>
|
204
|
-
```
|
205
|
-
|
206
|
-
The orders can be accessed through the `.orders` method and the filter
|
207
|
-
binding through `.filters`.
|
208
|
-
|
209
|
-
## Syntax ##
|
210
|
-
|
211
|
-
All arguments must be prefixed by "filter". It is possible to
|
212
|
-
query for specific data with filters, apply orders to the result
|
213
|
-
and to combine filters through AND, NOT and OR bindings.
|
214
|
-
|
215
|
-
The syntax builds under the filter parameter a virtual object.
|
216
|
-
The keys of the object are simulated through specifying `[{key}]`
|
217
|
-
in the passed query parameter. Thus `filter[param]` would point
|
218
|
-
to the param key in the filter object.
|
219
|
-
|
220
|
-
### Filter specification ###
|
221
|
-
|
222
|
-
The solution supports to query data through the `param` subkey.
|
223
|
-
|
224
|
-
```
|
225
|
-
filter[param][{parameter_name}][{operation}][{alias}] = {to_query_value}
|
226
|
-
```
|
227
|
-
|
228
|
-
The `operation` and `alias` parameters may be omitted. If no
|
229
|
-
`alias` is provided the given parameter name is used for it.
|
230
|
-
If no `operation` is given, the default one is used (in the
|
231
|
-
example this would be equal).
|
232
|
-
|
233
|
-
Example:
|
234
|
-
```
|
235
|
-
filter[param][phone_number][like]=001%
|
236
|
-
```
|
237
|
-
|
238
|
-
This would add a filter to all phone numbers which start with "001".
|
239
|
-
|
240
|
-
### Filter binding ###
|
241
|
-
|
242
|
-
Per default all filters are combined through AND clauses.
|
243
|
-
You can change that by specifying the `filter[binding]` argument.
|
244
|
-
|
245
|
-
This is where the aliases which you can define come into place.
|
246
|
-
The binding provides means to combine filters with AND and OR.
|
247
|
-
Also you are able to negate filters here.
|
248
|
-
|
249
|
-
The filters are addressed by their alias or name, if no alias is
|
250
|
-
provided.
|
251
|
-
|
252
|
-
If you have a filter `search_for_name`, `search_for_phone_number`
|
253
|
-
and `search_for_account_number` defined you can say
|
254
|
-
`search_for_name OR NOT search_for_number AND search_for_account_number`
|
255
|
-
by specifying the following filter:
|
256
|
-
|
257
|
-
```
|
258
|
-
filter[binding]=search_for_name|(!search_for_phone_number&search_for_account_number)
|
259
|
-
```
|
260
|
-
|
261
|
-
Even though the brackets are useless here, you can use them in
|
262
|
-
more complex filters.
|
263
|
-
|
264
|
-
The following table summarizes the possible configuration options:
|
265
|
-
<table>
|
266
|
-
<thead>
|
267
|
-
<tr>
|
268
|
-
<th>Type</th>
|
269
|
-
<th>Symbol</th>
|
270
|
-
<th>Example</th>
|
271
|
-
</tr>
|
272
|
-
</thead>
|
273
|
-
<tbody>
|
274
|
-
<tr>
|
275
|
-
<td>AND</td>
|
276
|
-
<td>&</td>
|
277
|
-
<td>a&b</td>
|
278
|
-
</tr>
|
279
|
-
<tr>
|
280
|
-
<td>OR</td>
|
281
|
-
<td>|</td>
|
282
|
-
<td>a|b</td>
|
283
|
-
</tr>
|
284
|
-
<tr>
|
285
|
-
<td>NOT</td>
|
286
|
-
<td>!</td>
|
287
|
-
<td>!a</td>
|
288
|
-
</tr>
|
289
|
-
<tr>
|
290
|
-
<td>Bracket</td>
|
291
|
-
<td>()</td>
|
292
|
-
<td>(a|b)&c</td>
|
293
|
-
</tr>
|
294
|
-
</tbody>
|
295
|
-
</table>
|
296
|
-
|
297
|
-
### Ordering ###
|
298
|
-
|
299
|
-
To specify a sort order of the results the `filter[order]` parameter
|
300
|
-
may be used. The value can be specified multiple times. To add
|
301
|
-
ordering you have to provide the name of the parameter which should
|
302
|
-
be ordered, not its alias!
|
303
|
-
|
304
|
-
If you want to order by `name`, `first_name` and in reverse order
|
305
|
-
`balance` you can do so by specifying the following query url
|
306
|
-
parameters:
|
307
|
-
|
308
|
-
```
|
309
|
-
filter[order]=name&filter[order]=first_name&filter[order]=desc(balance)
|
310
|
-
```
|
311
|
-
|
312
|
-
As you can see the `desc()` definition can be used to indicate
|
313
|
-
reverse ordering.
|
314
|
-
|
315
|
-
## License ##
|
316
|
-
|
317
|
-
The project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
|
318
|
-
|
319
|
-
## Used libraries ##
|
320
|
-
|
321
|
-
For parsing the query parameters the [`parslet`](https://kschiess.github.io/parslet/)
|
322
|
-
library is used. It is released under the [MIT License](https://github.com/kschiess/parslet/blob/master/LICENSE).
|
323
|
-
|
324
|
-
## Other Languages ##
|
325
|
-
|
326
|
-
This is a list of projects implementing the same API for other languages.
|
327
|
-
Currently this list only has one entry.
|
328
|
-
|
329
|
-
- Go - [go-filterparams](https://github.com/cbrand/go-filterparams)
|
330
|
-
- Python - [python-filterparams](https://github.com/cbrand/python-filterparams)
|
331
|
-
- JavaScript (Client) - [filterparams](https://github.com/cbrand/js-filterparams-client)
|
131
|
+
description: Parses filter parameters compatible query parameters and returns an object
|
132
|
+
which can be used to be mapped on top of a backend system. More information is available
|
133
|
+
on Github ( https://github.com/cbrand/ruby-filterparams ).
|
332
134
|
email: christoph@brand.rest
|
333
135
|
executables: []
|
334
136
|
extensions: []
|