Hyperclient

Hyperclient is a Ruby Hypermedia API client written in Ruby.

Documentation

Hyperclient API documentation on rdoc.info

Usage

Example API client:

api = Hyperclient.new('http://myapp.com/api').tap do |api|
  api.digest_auth('user', 'password')
  api.headers.update('accept-encoding' => 'deflate, gzip')
end

By default, Hyperclient adds application/json as Content-Type and Accept headers. It will also sent requests as JSON and parse JSON responses.

More examples

HAL

Hyperclient only works with JSON HAL friendly APIs. Learn about JSON HAL.

Resources

Hyperclient will try to fetch and discover the resources from your API.

Links

Accessing the links for a given resource is quite straightforward:

api._links.posts_categories
# => #<Resource ...>

Or omit _links, which will look for a link called "posts_categories" by default:

api.posts_categories
# => #<Resource ...>

You can also iterate between all the links:

api._links.each do |name, link|
  puts name, link._url
end

Actually, you can call any Enumerable method :D

If a Resource doesn't have friendly name you can always access it as a Hash:

api._links['http://myapi.org/rels/post_categories']

Embedded resources

Accessing embedded resources is similar to accessing links:

api._embedded.posts

Or omit the _embedded keyword. By default Hyperclient will look for a "posts" link, then for an embedded "posts" collection:

api.posts

And you can also iterate between them:

api.embedded.each do |name, resource|
  puts name, resource.attributes
end

You can even chain different calls (this also applies for links):

api.embedded.posts.first.links.author

Or omit the navigational structures:

api.posts.first.author

If you have a named link that retrieves an embedded collection of the same name, you can collapse the nested reference. The following statements produce identical results:

api.links.posts.embedded.posts.first

api.posts.first

Attributes

Not only you might have links and embedded resources in a Resource, but also its attributes:

api.embedded.posts.first.attributes
# => {title: 'Linting the hell out of your Ruby classes with Pelusa',
      teaser: 'Gain new insights about your code thanks to static analysis',
      body:   '...' }

You can access the attribute values via attribute methods, or as a hash:

api.posts.first.title
# => 'Linting the hell out of your Ruby classes with Pelusa'

api.embedded.posts.first.attributes.title
# => 'Linting the hell out of your Ruby classes with Pelusa'

api.embedded.posts.first.attributes['title']
# => 'Linting the hell out of your Ruby classes with Pelusa'

api.embedded.posts.first.attributes.fetch('title')
# => 'Linting the hell out of your Ruby classes with Pelusa'

HTTP

OK, navigating an API is really cool, but you may want to actually do something with it, right?

Hyperclient uses Faraday under the hood to perform HTTP calls. You can call any valid HTTP method on any Resource:

post = api._embedded.posts.first
post._get
post._head
post._put(title: 'New title')
post._patch(title: 'New title')
post._delete
post._options

posts = api._links.posts
posts._post(title: "I'm a blogger!", body: 'Wohoo!!')

If you have a templated link you can expand it like so:

api._links.post._expand(id: 3).first
# => #<Resource ...>

You can omit the "_expand" keyword.

api.post(id: 3).first
# => #<Resource ...>

You can access the Faraday connection (to add middlewares or do whatever you want) by calling connection on the entry point. As an example, you could use the faraday-http-cache-middleware:

api.connection.use :http_cache

Other

There's also a PHP library named HyperClient, if that's what you were looking for :)

TODO

• Resource permissions: Using the Allow header Hyperclient should be able to restrict the allowed method on a given Resource.
• Curie syntax support for links (see http://tools.ietf.org/html/draft-kelly-json-hal-03#section-8.2)
• Profile support for links

Contributing

• List of hyperclient contributors

• Fork the project.

• Make your feature addition or bug fix.

• Add specs for it. This is important so we don't break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. If you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull.

• Send me a pull request. Bonus points for topic branches.

License

MIT License. Copyright 2012-2014 Codegram Technologies