-
Notifications
You must be signed in to change notification settings - Fork 34
Dynamic clients
Heroics is completely dynamic under the hood. This is intended to make iterating on a JSON schema really easy because you can edit the schema and have a client without needing an intermediate build step. This functionality is now considered deprecated. You should be relying on the generated client instead.
That said, there's a builtin CLI (described below) and some projects continue to use the dynamic aspects of Heroics. The plan is to remove support for dynamic clients but, until then, the related documentation is here.
Heroics instantiates an HTTP client from a JSON schema. The client will make requests to the API using the credentials from the URL. The default headers will also be included in all requests.
require 'cgi'
require 'json'
require 'heroics'
username = CGI.escape('username')
token = 'token'
url = "https://#{username}:#{token}@api.heroku.com"
options = {default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'}}
data = JSON.parse(File.read('schema.json'))
schema = Heroics::Schema.new(data)
client = Heroics.client_from_schema(schema, url, options)The client will make requests to the API using an OAuth token when one is provided.
oauth_token = 'token'
url = "https://api.heroku.com"
options = {default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'}}
data = JSON.parse(File.read('schema.json'))
schema = Heroics::Schema.new(data)
client = Heroics.oauth_client_from_schema(oauth_token, schema, url, options)Heroics handles ETags and will cache data on the client if you provide a Moneta cache instance.
username = CGI.escape('username')
token = 'token'
url = "https://#{username}:#{token}@api.heroku.com/schema"
options = {default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'},
cache: Moneta.new(:File, dir: "#{Dir.home}/.heroics/heroku-api")}
data = JSON.parse(File.read('schema.json'))
schema = Heroics::Schema.new(data)
client = Heroics.client_from_schema(schema, url, options)The client exposes resources as top-level methods. Links described in the JSON schema for those resources are represented as methods on those top-level resources. For example, you can list the apps in your Heroku account:
apps = client.app.listThe response received from the server will be returned without
modifications. Response content with type application/json is
automatically decoded into a Ruby object.
Content ranges are handled transparently. In such cases the client
will return an Enumerator that can be used to access the data. It
only makes requests to the server to fetch additional data when the
current batch has been exhausted.
Heroics includes a builtin CLI that, like the client, is generated from a JSON schema.
username = 'username'
token = 'token'
url = "https://#{username}:#{token}@api.heroku.com/schema"
options = {
default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'},
cache: Moneta.new(:File, dir: "#{Dir.home}/.heroics/heroku-api")}
data = JSON.parse(File.read('schema.json'))
schema = Heroics::Schema.new(data)
cli = Heroics.cli_from_schema('heroku-api', STDOUT, schema, url, options)
cli.run(*ARGV)Running it without arguments displays usage information:
$ bundle exec bin/heroku-api
Usage: heroku-api <command> [<parameter> [...]] [<body>]
Help topics, type "heroku-api help <topic>" for more details:
account-feature:info Info for an existing account feature.
account-feature:list List existing account features.
account-feature:update Update an existing account feature.
account:change-email Change Email for account.
account:change-password Change Password for account.
account:info Info for account.
account:update Update account.
addon-service:info Info for existing addon-service.
addon-service:list List existing addon-services.
addon:create Create a new add-on.
--- 8< --- snip --- 8< ---
Use the help command to learn about commands:
$ bundle exec bin/heroku-api help app:create
Usage: heroku-api app:create <body>
Description:
Create a new app.
Body example:
{
"name": "example",
"region": "",
"stack": ""
}
In addition to being a fun way to play with your API it also gives you the basic information you need to use the same command from Ruby:
client.app.create({'name' => 'example',
'region' => '',
'stack' => ''})Commands that take arguments will list them in help output from the client.
$ bundle exec bin/heroku-api help app:info
Usage: heroku-api app:info <id|name>
Description:
Info for existing app.
This command needs an app's UUID or name:
info = client.app.info('sushi')Some commands need arguments as well as a body. In such cases, pass the arguments first with the body at the end.
Heroics comes with a builtin heroku-api program that serves as an
example and makes it easy to play with the Heroku Platform API.