Excon::Hypermedia

Teaches Excon how to talk to HyperMedia APIs.

Installation

Add this line to your application's Gemfile:

gem 'excon-hypermedia'

And then execute:

bundle

Or install it yourself as:

gem install excon-hypermedia

Usage

To let Excon know the API supports HyperMedia, simply enable the correct middleware (either globally, or per-connection):

Excon.defaults[:middlewares].push(Excon::HyperMedia::Middleware)

api = Excon.get('https://www.example.org/api.json')
api.class # => Excon::Response

Using the HyperMedia middleware, the Excon::Response object now knows how to handle the HyperMedia aspect of the API:

product = api.product(expand: { uid: 'bicycle' })
product.class # => Excon::Connection

response = product.get
response.class # => Excon::Response
response.body.class # => String

As seen above, you can expand URI Template variables using the expand option, provided by the excon-addressable library.

Since each new resource is simply an Excon::Response object, accessed through the default Excon::Connection object, all Excon-provided options are available as well:

product.get(idempotent: true, retry_limit: 6)

Links

You can access all links in a resource using the links method:

api.links.first.class # => Excon::HyperMedia::Link
api.links.first.name  # => 'product'
api.links.first.href  # => 'https://www.example.org/product/{uid}'

You can also access a link directly, using its name:

api.link('product').href # => 'https://www.example.org/product/{uid}'

If you want to access a relation through its link, but can't use the implicit naming, you can use the rel method:

api.links.last.name # => 'customer-orders'

# won't work, due to invalid ruby method name:
api.customer-orders(expand: { sort: 'desc' }) # => NoMethodError: undefined method `customer' 

# works
api.rel('customer-orders', expand: { sort: 'desc' })

Attributes

Attributes are available through the attributes method:

product.attributes.to_h # => { uid: 'bicycle', stock: 5 }
product.attributes.uid  # => 'bicycle'

License

The gem is available as open source under the terms of the MIT License.