Hyperclient is a Ruby Hypermedia API client written in Ruby.
Hyperclient API documentation on rdoc.info
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.
Hyperclient only works with JSON HAL friendly APIs. Learn about JSON HAL.
Hyperclient will try to fetch and discover the resources from your API.
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']
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
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.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'
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
There's also a PHP library named HyperClient, if that's what you were looking for :)
- Resource permissions: Using the
Allow
header Hyperclient should be able to restrict the allowed method on a givenResource
. - Curie syntax support for links (see http://tools.ietf.org/html/draft-kelly-json-hal-03#section-8.2)
- Profile support for links
-
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.
MIT License. Copyright 2012 Codegram Technologies