easy-jsonapi

Build Status Code Coverage License

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:

A middleware for filtering out non-compliant HTTP requests
A parser to interact with requests in a typical Object-Oriented Fashion, providing convenient and efficient access to headers, query parameters, and document members.
A validator to 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.

Installation

Add this line to your applications' Gemfile:

# Gemfile
gem 'easy-jsonapi'

then execute:

$ bundle
# ...

or manually via

$ gem install easy-jsonapi
# ...

Quick Start

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
```
use JSONAPI::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

Setup

Add the middleware to the stack in order to activate it.

Sinatra:

# app.rb
use JSONAPI::Middleware

Rails:

Edit config/environments/development.rb.

# 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

Rack Apps:

# config.ru
use JSONAPI::Middleware

Functionality

The easy-jsonapi middleware can operate in development or production mode.

If 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::JSONParseError when an included body is not valid JSON
JSONAPI::Exceptions::HeaderExceptions::InvalidHeader when an included header is non-compliant
JSONAPI::Exceptions::QueryParamExceptions::InvalidQueryParam when an included query parameter is non-compliant
JSONAPI::Exceptions::DocumentExceptions::InvalidDocument when the body is included and non-compliant

If 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.

User Configurations

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 env variable.

With Rails or Sinatra you can access this by using:

request.env

For rack apps you get env from the call method:

def call(env)

  # ...

end

To parse:

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

The 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

The headers param is a hash of String => String or Symbol => String of the header keys and values. The 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.

Acknowledgements

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!

Releases

See CHANGELOG.

License

easy-jsonapi is released under the MIT License.

Contributing

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.