The gem that makes using JSON:API EASY!
Ever wanted the benefits of JSONAPI without the learning curve of the 34-page spec? Well, now you can! Introducing easy-jsonapi, a fully-compliant, lightweight, and intuitive ruby gem that currently provides 3 main use cases:
middlewarefor filtering out non-compliant HTTP requests
parserto interact with requests in a typical Object-Oriented Fashion, providing convenient and efficient access to headers, query parameters, and document members.
validatorto check your serialized responses for JSONAPI compliance.
With its only gem dependency being Oj, easy-jsonapi is a lightweight, dependable tool, featuring comprehensive error messages and over 525 unit tests allowing developers to spend less time debugging and more time creating.
As a bonus, flexible user configurations can be added to the middleware providing custom screening on all requests or individual requests depending on the resource type of the endpoint and the user-defined document, header, or query param restrictions.
Add this line to your applications' Gemfile:
# Gemfile gem 'easy-jsonapi'
$ bundle # ...
or manually via
$ gem install easy-jsonapi # ...
easy-jsonapi's 3 main use cases can be used together or separately, so to get started quickly, do any of the 3 below to begin enjoying the convenience of the library.
- Set up the middleware
- Parse the rack environment variable and get access to request components (assumes valid JSON:API requests -- use with middleware to ensure valid requests)
j_req = JSONAPI::Parser.parse_request(env) j_req.headers.content_type # => "application/vnd.api+json" j_req.params.page.offset # => "1" j_req.body.data.type # => "person"
- Validate your serialized JSON:API before returning it to your clients.
begin JSONAPI::Response.validate(headers, body) rescue => error # ... end
Using The Middleware
Add the middleware to the stack in order to activate it.
# app.rb use JSONAPI::Middleware
# config/environments/development.rb MyApp::Application.configure do # Add JSONAPI::Middleware to the bottom of the middleware stack config.middleware.insert_after ActionDispatch::Static, JSONAPI::Middleware # or, if you're using better_errors: config.middleware.insert_before Rack::Lock, JSONAPI::Middleware # ... end
# config.ru use JSONAPI::Middleware
The easy-jsonapi middleware can operate in development or production mode.
ENV['RACK_ENV'] is set to
'development' or not set at all, the middleware will be operating in development mode.
When the middleware is in development mode it will raise an exception wherever it finds the http request to be non JSONAPI compliant.
The types of exceptions it will raise are:
JSONAPI::Exceptions::JSONParseErrorwhen an included body is not valid JSON
JSONAPI::Exceptions::HeaderExceptions::InvalidHeaderwhen an included header is non-compliant
JSONAPI::Exceptions::QueryParamExceptions::InvalidQueryParamwhen an included query parameter is non-compliant
JSONAPI::Exceptions::DocumentExceptions::InvalidDocumentwhen the body is included and non-compliant
ENV['RACK_ENV'] is set to something other than
'development', then the middleware will return the appropriate status code error given the JSON:API clause the headers, query params, or document violates.
easy-jsonapi has a fair amount of flexibility when it comes to user configurations but also plenty of room for to add more features. To see the currently available configurations see UsingUserConfigurations and to propose a new feature create a pull request or ticket on the dev repository.
Using the Request Parser
The request parser works by parsing the rack
With Rails or Sinatra you can access this by using:
For rack apps you get env from the call method:
def call(env) # ... end
require 'easy/jsonapi' # ... jsonapi_req = JSONAPI::Parser.parse_request(env)
This returns a
JSONAPI::Request object that can be used to access the collection of query params, collection of headers, and the body of the request. To see example usage, see Using the Request Object.
Using the Serialized Response Validator
JSONAPI::Response module is responsible for validating whether a serialized response is fully JSONAPI compliant or not.
The following method is provided to validate the response:
require 'easy/jsonapi' # ... application code begin JSONAPI::Response.validate(headers, body) rescue => error # ... handling end
headers param is a hash of
String => String or
Symbol => String of the header keys and values.
body param is either the JSON body or a ruby hash representation of the body.
See the rubydocs for more on the Serialized Response Validator.
The exception checking strategy for
JSONAPI::Exceptions::DocumentExceptions and some initial compliance checks are based off jsonapi-parser. We would like to thank the jsonapi-rb team for the document validation work and to all our contributors and users for the continuous support!
easy-jsonapi is released under the MIT License.
Bug reports and pull requests are welcome here on Github. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Code of Conduct.
Code of Conduct
Everyone interacting in the easy-jsonapi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the Code of Conduct.