module Heroics
Heroics
is an HTTP client for an API described by a JSON schema.
Constants
- VERSION
Public Class Methods
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
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
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
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 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 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
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
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
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
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
Public Instance Methods
# File lib/heroics.rb, line 14 def default_configuration(&block) block ||= lambda { |c| } Heroics::Configuration.defaults.tap(&block) end