HalInterpretation

Build ActiveModels from HAL documents with good error messages for validity issues.

Usage

HalInterpretation provides a DSL for declaring how to build one or more ActiveModel objects from a HAL document.

class UserHalInterpreter
  include HalInterpretation

  item_class User

  extract :name
  extract :address_line, from: "address/line1"
end

To interpret a HAL document simply create a new interpreter from the JSON document to interpret and then call its #items method.

class Users < ApplicationController
  def create
    @users = UserHalInterpreter.new_from_json(request.raw_post).items

  rescue HalInterpretation::InvalidRepresentationError => err
    render template: "shared/error", status: 422, locals: { problems: err.problems }
  end
end

The items method returns an Enumerable of valid item_class objects.

Errors

If the JSON being interpreted is invalid or malformed HalInterpretation provides a list of the problems encountered through the #problems method. Each problem message includes a JSON pointer to the exact location in the original document that caused the problem. This is true even when interpreting collections for example if name of the third user in a collection is null the problem message would be

/_embedded/item/2/name cannot be blank

Validity is determined using the #valid? method of the models being built.

Installation

Add this line to your application's Gemfile:

gem 'hal-interpretation'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hal-interpretation

Contributing

Fork it ( http://github.com/pezra/hal-interpretation/fork )
Create your feature branch (git checkout -b my-new-feature)
Make your improvement
Update the version following semver rules
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request