Client framework for consuming JSONAPI services in Ruby
Ruby
Latest commit 1617f9b Mar 19, 2015 @jsmestad Update README.md

README.md

JSONAPI::Consumer

An ActiveModel-compliant consumer framework for communicating with JSONAPI-based APIs.

Build Status

JSONAPI Compatibility

The master branch is features compatibility with JSONAPI (prior to RC). If you are looking for JSONAPI RC3 (soon to be 1.0) check out the develop branch for that.

Installation

Add this line to your application's Gemfile:

gem 'jsonapi-consumer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jsonapi-consumer

Usage

It's suggested to create a base resource for the whole API that you can re-use.

class Base
  include JSONAPI::Consumer::Resource

  self.host = 'http://localhost:3000/api/'
end

Then inherit from that Base class for each resource defined in your API.

module Blog

  class Author < Base
    has_many :posts, class_name: 'Blog::Post'
  end

  class Post < Base
    has_one :user, class_name: 'Blog::User'
    has_many :comments, class_name: 'Blog::Comment'
  end

  class User < Base

  end

  class Comment < Base

  end

end

Additional Features

Dynamic Objects

By default calling .new or .build on a resource will give you an empty object with no attributes defined. This is less than ideal when building forms with something like Rails' FormBuilder.

We suggest setting up your model to do a GET /{resource_name}/new if your server supports it and using .build instead of .new. This will populate the object with defaults set by the server response.

class User
  include JSONAPI::Consumer::Resource

  self.request_new_object_on_build = true

  # .build will now call GET /users/new
end

Testing

We suggest Webmock at this stage in development. We plan to add test helpers before the first major release.

Contributing

  1. Fork it ( https://github.com/jsmestad/jsonapi-consumer/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Copyright & License

JSONAPI::Consumer is distributed under the Apache 2.0 License. See LICENSE.txt file for more information.