HyperClient is a Ruby Hypermedia API client.
Ruby
Pull request Compare This branch is 233 commits behind codegram:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
lib
test
.gitignore
.rvmrc
.travis.yml
.yardopts
Gemfile
Guardfile
LICENSE
MIT-LICENSE
Rakefile
Readme.md
hyperclient.gemspec

Readme.md

Hyperclient

Build Status Dependency Status Code Climate

Hyperclient is a Ruby Hypermedia API client written in Ruby.

Documentation

Hyperclient API documentation on rdoc.info

Usage

Example API client:

options = {}
options[:auth]    = {type: :digest, user:, 'user', password: 'password'}
options[:headers] = {'accept-encoding' => 'deflate, gzip'}
options[:debug]   = true

api = Hyperclient::EntryPoint.new('http://myapp.com/api', options)

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 HTTParty 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.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 ...>

TODO

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