https://github.com/evalmee/json_api_filter
Filter for rails controller based on JsonAPI spec
https://github.com/evalmee/json_api_filter
jsonapi rails ruby
Last synced: 3 months ago
JSON representation
Filter for rails controller based on JsonAPI spec
- Host: GitHub
- URL: https://github.com/evalmee/json_api_filter
- Owner: evalmee
- License: mit
- Created: 2019-11-19T18:41:39.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-08T22:43:01.000Z (over 3 years ago)
- Last Synced: 2026-01-13T06:59:11.227Z (5 months ago)
- Topics: jsonapi, rails, ruby
- Language: Ruby
- Homepage:
- Size: 87.9 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# JsonApiFilter
Filter for rails controller based on JsonAPI spec: `/books?filter[library_id]=1,2&filter[author_id][eq]=12&filter[created_at][gt]=2021-02-02`
[](https://codeclimate.com/github/evalmee/json_api_filter/maintainability)
[](https://badge.fury.io/rb/json_api_filter)
[](https://travis-ci.com/evalmee/json_api_filter)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'json_api_filter'
```
And then execute:
```bash
$ bundle
```
Or install it yourself as:
```bash
$ gem install json_api_filter
```
## Usage
### Quick start
To filter this request `/books?filter[library_id]=1,2&filter[author_id]=12&search=Lord of the ring&include=users,users.posts`
```ruby
class Book < ApplicationController
include JsonApiFilter
permitted_filters %i[library_id author_id]
permitted_searches :user_search
permitted_inclusions %i[users users.posts]
def index
@books = json_api_filter(Book, params)
inclusions = json_api_inclusions(params) # returns [:users, :'users.posts']
# then use `inclusions` in the serialiser
BookSerializer.new(@books, include: inclusions).serializable_hash.to_json
end
end
```
- `permitted_filters` let you define allowed attributes to filter on (mandatory)
- `permitted_searches` let you define the allowed search method defined in you model what will be called if you pass `search` params in your request (can be a pg_search scope)
- `permitted_inclusions` let you define the allowed inclusions
- `json_api_filter(scope, params)` return an active record relation (`Book::` in this example)
# Use inclusions in serializers
# Handling errors
If an endpoint does not support the include parameter, it MUST respond with 400 Bad Request to any requests that include it.
```ruby
class Book < ApplicationController
include JsonApiFilter
permitted_filters %i[library_id author_id]
permitted_searches :user_search
rescue_from JsonApiFilter::MissingPermittedInclusionError, with: :render_400
def index
@books = json_api_filter(Book, params)
inclusions = json_api_inclusions(params) # raises JsonApiFilter::MissingPermittedInclusionError
end
private
def render_400(exception)
render json: exception, status: 400
end
end
```
If a server is unable to identify a relationship path or does not support inclusion of resources from a path, it MUST respond with 400 Bad Request.
This request should return a 400 status:
`/books?filter[library_id]=1,2&filter[author_id]=12&search=Lord of the ring&include=users,users.posts, users.addresses`
```ruby
class Book < ApplicationController
include JsonApiFilter
permitted_filters %i[library_id author_id]
permitted_searches :user_search
permitted_inclusions %i[users users.posts]
rescue_from JsonApiFilter::UnknownInclusionsError, with: :render_400
def index
@books = json_api_filter(Book, params)
inclusions = json_api_inclusions(params) # raises JsonApiFilter::UnknownInclusionsError
end
private
def render_400(exception)
render json: exception, status: 400
end
end
```
## Migration from 0.1
0.2.x version is not compatible with 0.1
In your controller, you will have to replace all occurrences of `attr_filter` as bellow :
### Before
```ruby
def index
@books = Book.all.where(attr_filter(params))
end
```
### After
```ruby
def index
@books = json_api_filter(Book, params)
end
```
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Blaked84/json_api_filter. 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.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
Everyone interacting in the JsonApiFilter project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Blaked84/json_api_filter/blob/master/CODE_OF_CONDUCT.md).