Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby HTTP client for APIs represented with JSON schema

Merge pull request #68 from interagent/brandur-thread-safe-sockets

Add thread_safe_sockets option to Excon connection
latest commit bd9f55612b
@geemus geemus authored

Build Status


Ruby HTTP client generator for APIs represented with JSON schema.


Add this line to your application's Gemfile:

gem 'heroics'

And then execute:

$ bundle

Or install it yourself as:

$ gem install heroics


Generating a client

Heroics generates an HTTP client from a JSON schema that describes your API. Look at prmd for tooling to help write a JSON schema. When you have a JSON schema prepared you can generate a client for your API:

bin/heroics-generate MyApp schema.json > client.rb

Passing custom headers

If your client needs to pass custom headers with each request these can be specified using -H:

heroics-generate \
  -H "Accept: application/vnd.myapp+json; version=3" \
  MyApp \
  schema.json \ > client.rb

Pass multiple -H options if you need more than one custom header.

Client-side caching

The generated client sends and caches ETags received from the server. By default, this data is cached in memory and is only used during the lifetime of a single instance. You can specify a directory for cache data:

heroics-generate \
  -c "~/.heroics/myapp" \
  MyApp \
  schema.json \ > client.rb

~ will automatically be expanded to the user's home directory. Be sure to wrap such paths in quotes to avoid the shell expanding it to the directory you built the client in.

Generating API documentation

The generated client has Yard-compatible docstrings. You can generate documentation using yardoc:

yard doc -m markdown client.rb

This will generate HTML in the docs directory. Note that Yard creates an _index.html page won't be served by Jekyll on GitHub Pages. Add a .nojekyll file to your project to prevent GitHub from passing the content through Jekyll.

Handling failures

The client uses Excon under the hood and raises Excon errors when failures occur.

begin{'name' => 'example'})
rescue Excon::Errors::Forbidden => error
  puts error


  1. Fork the repository
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new pull request
Something went wrong with that request. Please try again.