module Heroics

Heroics is an HTTP client for an API described by a JSON schema.

Constants

VERSION

Public Class Methods

cli_from_schema(name, output, schema, url, options={}) click to toggle source

Create a CLI from a JSON schema.

@param name [String] The name of the CLI. @param output [IO] The stream to write to. @param schema [Hash] The JSON schema to use with the CLI. @param url [String] The URL used by the generated CLI when it makes

requests.

@param options [Hash] Configuration for links. Possible keys include:

- default_headers: Optionally, a set of headers to include in every
  request made by the CLI.  Default is no custom headers.
- cache: Optionally, a Moneta-compatible cache to store ETags.  Default
  is no caching.

@return [CLI] A CLI with commands generated from the JSON schema.

# File lib/heroics/cli.rb, line 78
def self.cli_from_schema(name, output, schema, url, options={})
  client = client_from_schema(schema, url, options)
  commands = {}
  schema.resources.each do |resource_schema|
    resource_schema.links.each do |link_schema|
      command = Command.new(name, link_schema, client, output)
      commands[command.name] = command
    end
  end
  CLI.new(name, commands, output)
end

client_from_schema(schema, url, options={}) click to toggle source

Create an HTTP client from a JSON schema.

@param schema [Schema] The JSON schema to build an HTTP client for. @param url [String] The URL the generated client should use when making

requests.  Include the username and password to use with HTTP basic
auth.

@param options [Hash] Configuration for links. Possible keys include:

- default_headers: Optionally, a set of headers to include in every
  request made by the client.  Default is no custom headers.
- cache: Optionally, a Moneta-compatible cache to store ETags.  Default
  is no caching.

@return [Client] A client with resources and links from the JSON schema.

# File lib/heroics/client.rb, line 59
def self.client_from_schema(schema, url, options={})
  resources = {}
  schema.resources.each do |resource_schema|
    links = {}
    resource_schema.links.each do |link_schema|
      links[link_schema.name] = Link.new(url, link_schema, options)
    end
    resources[resource_schema.name] = Resource.new(links)
  end
  Client.new(resources, url)
end

download_schema(url, options={}) click to toggle source

Download a JSON schema from a URL.

@param url [String] The URL for the schema. @param options [Hash] Configuration for links. Possible keys include:

- default_headers: Optionally, a set of headers to include in every
  request made by the client.  Default is no custom headers.

@return [Schema] The downloaded JSON schema.

# File lib/heroics/schema.rb, line 356
def self.download_schema(url, options={})
  default_headers = options.fetch(:default_headers, {})
  response = Excon.get(url, headers: default_headers, expects: [200, 201])
  Schema.new(MultiJson.load(response.body))
end

generate_client() click to toggle source

Generate a static client that uses Heroics under the hood. This is a good option if you want to ship a gem or generate API documentation using Yard.

# File lib/heroics/client_generator.rb, line 5
def self.generate_client
  filename = File.dirname(__FILE__) + '/views/client.erb'
  eruby = Erubis::Eruby.new(File.read(filename))
  context = build_context(Heroics::Configuration.defaults.module_name,
    Heroics::Configuration.defaults.schema,
    Heroics::Configuration.defaults.base_url,
    Heroics::Configuration.defaults.options)
  eruby.evaluate(context)
end

oauth_client_from_schema(oauth_token, schema, url, options={}) click to toggle source

Create an HTTP client with OAuth credentials from a JSON schema.

@param oauth_token [String] The OAuth token to pass using the `Bearer`

authorization mechanism.

@param schema [Schema] The JSON schema to build an HTTP client for. @param url [String] The URL the generated client should use when making

requests.

@param options [Hash] Configuration for links. Possible keys include:

- default_headers: Optionally, a set of headers to include in every
  request made by the client.  Default is no custom headers.
- cache: Optionally, a Moneta-compatible cache to store ETags.  Default
  is no caching.

@return [Client] A client with resources and links from the JSON schema.

# File lib/heroics/client.rb, line 84
def self.oauth_client_from_schema(oauth_token, schema, url, options={})
  authorization = "Bearer #{oauth_token}"
  # Don't mutate user-supplied data.
  options = Marshal.load(Marshal.dump(options))
  if !options.has_key?(:default_headers)
    options[:default_headers] = {}
  end
  options[:default_headers].merge!({"Authorization" => authorization})
  client_from_schema(schema, url, options)
end

pretty_name(name) click to toggle source

Process a name to make it suitable for use as a pretty command name.

@param name [String] The name to process. @return [String] The new name with capitals converted to lowercase, and

underscores and spaces converted to dashes.

# File lib/heroics/naming.rb, line 26
def self.pretty_name(name)
  name.downcase.gsub(/[_ ]/, '-')
end

ruby_name(name) click to toggle source

Process a name to make it suitable for use as a Ruby method name.

@param name [String] The name to process. @return [String] The new name with capitals converted to lowercase,

and characters replaced or removed based on the
Configuration.ruby_names_replacement_patterns rules

@raise [SchemaError] Raised if the name contains invalid characters.

# File lib/heroics/naming.rb, line 10
def self.ruby_name(name)
  patterns = Heroics::Configuration.defaults.ruby_name_replacement_patterns

  ruby_name = patterns.reduce(name.downcase) do |memo, (regex, replacement)|
    memo.gsub(regex, replacement)
  end

  raise SchemaError.new("Name '#{name}' converts to invalid Ruby name '#{ruby_name}'.") if ruby_name =~ /\W/
  ruby_name
end

token_client_from_schema(token, schema, url, options={}) click to toggle source

Create an HTTP client with Token credentials from a JSON schema.

@param oauth_token [String] The token to pass using the `Bearer`

authorization mechanism.

@param schema [Schema] The JSON schema to build an HTTP client for. @param url [String] The URL the generated client should use when making

requests.

@param options [Hash] Configuration for links. Possible keys include:

- default_headers: Optionally, a set of headers to include in every
  request made by the client.  Default is no custom headers.
- cache: Optionally, a Moneta-compatible cache to store ETags.  Default
  is no caching.

@return [Client] A client with resources and links from the JSON schema.

# File lib/heroics/client.rb, line 108
def self.token_client_from_schema(token, schema, url, options={})
  authorization = "Token token=#{token}"
  # Don't mutate user-supplied data.
  options = Marshal.load(Marshal.dump(options))
  if !options.has_key?(:default_headers)
    options[:default_headers] = {}
  end
  options[:default_headers].merge!({"Authorization" => authorization})
  client_from_schema(schema, url, options)
end

Private Class Methods

build_context(module_name, schema, base_url, options) click to toggle source

Process the schema to build up the context needed to render the source template.

# File lib/heroics/client_generator.rb, line 19
def self.build_context(module_name, schema, base_url, options)
  resources = []
  schema.resources.each do |resource_schema|
    links = []
    resource_schema.links.each do |link_schema|
      links << GeneratorLink.new(link_schema.name,
                                 link_schema.description,
                                 link_schema.parameter_details,
                                 link_schema.needs_request_body?)
    end
    resources << GeneratorResource.new(resource_schema.name,
                                       resource_schema.description,
                                       links)
  end

  {
    module_name: module_name,
    url: base_url,
    default_headers: options.fetch(:default_headers, {}),
    cache: options.fetch(:cache, {}),
    description: schema.description,
    schema: MultiJson.dump(schema.schema, pretty:true),
    resources: resources
  }
end

camel_case(text) click to toggle source

Convert a lower_case_name to CamelCase.

# File lib/heroics/client_generator.rb, line 88
def self.camel_case(text)
  return text if text !~ /_/ && text =~ /[A-Z]+.*/
  text = text.split('_').map{ |element| element.capitalize }.join
  [/^Ssl/, /^Http/, /^Xml/].each do |replace|
    text.sub!(replace) { |match| match.upcase }
  end
  text
end

Public Instance Methods

default_configuration(&block) click to toggle source

# File lib/heroics.rb, line 14
def default_configuration(&block)
  block ||= lambda { |c| }
  Heroics::Configuration.defaults.tap(&block)
end