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.merge({'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 ...>

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

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

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:   '...' }

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 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 Codegram Technologies