Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/visualitypl/jsonapi_parameters
Rails-way to consume JSON:API input
https://github.com/visualitypl/jsonapi_parameters
api json json-api jsonapi rails ruby ruby-on-rails
Last synced: 3 days ago
JSON representation
Rails-way to consume JSON:API input
- Host: GitHub
- URL: https://github.com/visualitypl/jsonapi_parameters
- Owner: visualitypl
- License: mit
- Created: 2019-01-15T17:37:27.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-07-19T18:16:43.000Z (over 2 years ago)
- Last Synced: 2024-12-15T22:27:46.238Z (9 days ago)
- Topics: api, json, json-api, jsonapi, rails, ruby, ruby-on-rails
- Language: Ruby
- Homepage: https://rubygems.org/gems/jsonapi_parameters
- Size: 145 KB
- Stars: 58
- Watchers: 10
- Forks: 8
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# JsonApi::Parameters
Simple [JSON:API](https://jsonapi.org/) compliant parameters translator.
[](https://badge.fury.io/rb/jsonapi_parameters)
[](https://codeclimate.com/github/visualitypl/jsonapi_parameters/maintainability)
[](https://codeclimate.com/github/visualitypl/jsonapi_parameters/test_coverage)
[](https://circleci.com/gh/visualitypl/jsonapi_parameters)
[Documentation](https://github.com/visualitypl/jsonapi_parameters/wiki)
## Usage
### Installation
Add this line to your application's Gemfile:
```ruby
gem 'jsonapi_parameters'
```
And then execute:
```bash
$ bundle
```
Or install it yourself as:
```bash
$ gem install jsonapi_parameters
```
### Rails
Usually your strong parameters in controller are invoked this way:
```ruby
def create
model = Model.new(create_params)
if model.save
...
else
head 500
end
end
private
def create_params
params.require(:model).permit(:name)
end
```
With jsonapi_parameters, the difference is just the params:
```ruby
def create_params
params.from_jsonapi.require(:model).permit(:name)
end
```
#### Relationships
JsonApi::Parameters supports ActiveRecord relationship parameters, including [nested attributes](https://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html).
Relationship parameters are being read from two optional trees:
* `relationships`,
* `included`
If you provide any related resources in the `relationships` table, this gem will also look for corresponding, `included` resources and their attributes. Thanks to that this gem supports nested attributes, and will try to translate these included resources and pass them along.
For more examples take a look at [Relationships](https://github.com/visualitypl/jsonapi_parameters/wiki/Relationships) in the wiki documentation.
### Plain Ruby / outside Rails
```ruby
params = { # JSON:API compliant parameters here
# ...
}
class Translator
include JsonApi::Parameters
end
translator = Translator.new
translator.jsonapify(params)
```
## Mime Type
As [stated in the JSON:API specification](https://jsonapi.org/#mime-types) correct mime type for JSON:API input should be [`application/vnd.api+json`](http://www.iana.org/assignments/media-types/application/vnd.api+json).
This gem's intention is to make input consumption as easy as possible. Hence, it [registers this mime type for you](lib/jsonapi_parameters/core_ext/action_dispatch/http/mime_type.rb).
## Stack limit
In theory, any payload may consist of infinite amount of relationships (and so each relationship may have its own, included, infinite amount of nested relationships).
Because of that, it is a potential vector of attack.
For this reason we have introduced a default limit of stack levels that JsonApi::Parameters will go down through while parsing the payloads.
This default limit is 3, and can be overwritten by specifying the custom limit.
#### Ruby
```ruby
class Translator
include JsonApi::Parameters
end
translator = Translator.new
translator.jsonapify(custom_stack_limit: 4)
# OR
translator.stack_limit = 4
translator.jsonapify.(...)
```
#### Rails
```ruby
def create_params
params.from_jsonapi(custom_stack_limit: 4).require(:user).permit(
entities_attributes: { subentities_attributes: { ... } }
)
end
# OR
def create_params
params.stack_level = 4
params.from_jsonapi.require(:user).permit(entities_attributes: { subentities_attributes: { ... } })
ensure
params.reset_stack_limit!
end
```
## Customization
If you need custom relationship handling (for instance, if you have a relationship named `scissors` that is plural, but it actually is a single entity), you can use Handlers to define appropriate behaviour.
Read more at [Relationship Handlers](https://github.com/visualitypl/jsonapi_parameters/wiki/Relationship-handlers).
## Team
Project started by [Jasiek Matusz](https://github.com/Marahin).
Currently, jsonapi_parameters is maintained by Visuality's [Open Source Commitee](https://www.visuality.pl/open-source).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).