Module: Heroics

Extended by:
Heroics
Included in:
Heroics
Defined in:
lib/heroics.rb,
lib/heroics/cli.rb,
lib/heroics/link.rb,
lib/heroics/client.rb,
lib/heroics/errors.rb,
lib/heroics/naming.rb,
lib/heroics/schema.rb,
lib/heroics/command.rb,
lib/heroics/version.rb,
lib/heroics/resource.rb,
lib/heroics/configuration.rb,
lib/heroics/client_generator.rb

Overview

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

Defined Under Namespace

Classes: BodyParameter, CLI, Client, Command, Configuration, GeneratorLink, GeneratorResource, Link, LinkSchema, Parameter, ParameterChoice, Resource, ResourceSchema, Schema, SchemaError

Constant Summary collapse

VERSION = 
'0.0.19'

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.cli_from_schema(name, output, schema, url, options = {}) ⇒ CLI

Create a CLI from a JSON schema.



78
79
80
81
82
83
84
85
86
87
88
 
# 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 = {}) ⇒ Client

Create an HTTP client from a JSON schema.



57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/heroics/client.rb', line 57

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 = {}) ⇒ Schema

Download a JSON schema from a URL.



347
348
349
350
351
 
# File 'lib/heroics/schema.rb', line 347

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 ⇒ Object

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.



5
6
7
8
9
10
11
12
13
 
# 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 = {}) ⇒ Client

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



82
83
84
85
86
87
88
89
90
91
 
# File 'lib/heroics/client.rb', line 82

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) ⇒ String

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



26
27
28
 
# File 'lib/heroics/naming.rb', line 26

def self.pretty_name(name)
  name.downcase.gsub(/[_ ]/, '-')
end

.ruby_name(name) ⇒ String

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

Raises:

  • (SchemaError) —

    Raised if the name contains invalid characters.



10
11
12
13
14
15
16
17
18
19
 
# 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 = {}) ⇒ Client

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



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/heroics/client.rb', line 106

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

Instance Method Details

#default_configuration(&block) ⇒ Object 



13
14
15
16
 
# File 'lib/heroics.rb', line 13

def default_configuration(&block)
  block ||= lambda { |c| }
  Heroics::Configuration.defaults.tap(&block)
end