heroics 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57ff3e602b9779ad560f218f14288d8871402d33
-  data.tar.gz: 6763bba24c1ccb627963116ee6f43ed341113703
+  metadata.gz: 16b5b5b9ec40a80d7ac06af58ebf2be1e0c773fe
+  data.tar.gz: a695f11ee1b3eb7841def942d6239c3a589c0fba
 SHA512:
-  metadata.gz: 97435f7696ba084ec24a487ea3a652a880100124981e1ebf7f1e91bebf8baff64c6b281dca44e8480d550d3097ac368e36ddd8a466114841b9811b8dd2f4e072
-  data.tar.gz: 05282988882070b71e6cf9c9c6834bb65fc91c783da88c08e0163b54a21e97dedec950d9b187593cbed23b18c379404d0a6acb091800cb37adbdf586386c1fd9
+  metadata.gz: 3a4e120811c3b4cef5d0cd919173c9b89e8e2b39834bbc103681056fa3e4355b371ff9a7cf27c1b22b3114e1c962f9c6fe45cf11a9a4d5317e9d6ce9d64e5e97
+  data.tar.gz: 5ad761a53a1baeb2cbbc6d33aa0239c4742eb61406194a0e68b551ea6283372c84f320b631d255bdbd8e7eba524bf86e284eded0d4576d654390f444f73bb983

data/README.md

@@ -1,7 +1,7 @@
-[![Build Status](https://travis-ci.org/heroku/heroics.png?branch=master)](https://travis-ci.org/heroku/heroics)
+[![Build Status](https://travis-ci.org/interagent/heroics.png?branch=master)](https://travis-ci.org/interagent/heroics)
 # Heroics
 
-Ruby HTTP client for APIs represented with JSON schema.
+Ruby HTTP client generator for APIs represented with JSON schema.
 
 ## Installation
 
@@ -19,180 +19,78 @@ Or install it yourself as:
 
 ## Usage
 
-### Instantiate a client from a JSON schema with basic credentials
+### Generating a client
 
-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.
+Heroics generates an HTTP client from a JSON schema that describes your API.
+Look at [prmd](https://github.com/interagent/prmd) for tooling to help write a
+JSON schema.  When you have a JSON schema prepared you can generate a client
+for your API:
 
-```ruby
-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)
 ```
-
-### Instantiate a client from a JSON schema with an OAuth token
-
-The client will make requests to the API using an OAuth token when one is
-provided.
-
-```ruby
-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)
+bin/heroics-generator MyApp schema.json https://api.myapp.com > client.rb
 ```
 
-### Client-side caching
+### Passing custom headers
 
-Heroics handles ETags and will cache data on the client if you provide
-a [Moneta](https://github.com/minad/moneta) cache instance.
+If your client needs to pass custom headers with each request these can be
+specified using `-H`:
 
-```ruby
-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)
 ```
-
-### Making requests
-
-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](https://devcenter.heroku.com/articles/platform-api-reference#app-list)
-in your Heroku account:
-
-```ruby
-apps = client.app.list
+bin/heroics-generator \
+  -H "Accept: application/vnd.myapp+json; version=3" \
+  MyApp \
+  schema.json \
+  https://api.myapp.com > client.rb
 ```
 
-The response received from the server will be returned without
-modifications.  Response content with type `application/json` is
-automatically decoded into a Ruby object.
-
-### Handling content ranges
+Pass multiple `-H` options if you need more than one custom header.
 
-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.
-
-### Command-line interface
-
-Heroics includes a builtin CLI that, like the client, is generated
-from a JSON schema.
-
-```ruby
-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)
-```
+### Client-side caching
 
-Running it without arguments displays usage information:
+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:
 
 ```
-$ 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< ---
+bin/heroics-generator \
+  -c "~/.heroics/myapp" \
+  MyApp \
+  schema.json \
+  https://api.myapp.com > client.rb
 ```
 
-Use the `help` command to learn about commands:
+`~` 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.
 
-```
-$ 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": ""
-  }
-```
+### Generating API documentation
 
-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:
+The generated client has [Yard](http://yardoc.org/)-compatible docstrings.
+You can generate documentation using `yardoc`:
 
-```ruby
-client.app.create({'name'   => 'example',
-                   'region' => '',
-                   'stack'  => ''})
 ```
-
-### Command arguments
-
-Commands that take arguments will list them in help output from the
-client.
-
+yard doc -m markdown client.rb
 ```
-$ 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:
+This will generate HTML in the `docs` directory.  Note that Yard creates an
+`_index.html` page that doesn't appear to be compatible with GitHub Pages.  If
+you're hosting your content there you can change the links:
 
-```ruby
-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.
-
-### Using the Heroku API
-
-Heroics comes with a builtin `heroku-api` program that serves as an
-example and makes it easy to play with the [Heroku Platform API](https://devcenter.heroku.com/articles/platform-api-reference).
+cd docs
+sed -e 's/_index\.html/index\.html/g' -i `grep _index.html * -rl`
+```
 
 ### Handling failures
 
-The client uses [Excon](https://github.com/geemus/excon) under the hood and raises Excon errors when
-failures occur.
+The client uses [Excon](https://github.com/geemus/excon) under the hood and
+raises Excon errors when failures occur.
 
 ```ruby
 begin
   client.app.create({'name' => 'example'})
-rescue Excon::Errors::Forbidden => e
-  puts e
+rescue Excon::Errors::Forbidden => error
+  puts error
 end
 ```
 

data/bin/heroics-generate

@@ -3,20 +3,37 @@
 require 'optparse'
 require 'heroics'
 
-options = {}
+options = {headers: {}, cache_path: nil}
 option_parser = OptionParser.new do |opts|
   opts.banner = 'Usage: heroics-generate module_name schema_filename url'
-  opts.on( '-h', '--help', 'Display this screen' ) do
+
+  opts.on('-h', '--help', 'Display this screen') do
     puts opts
     exit
   end
+
+  opts.on('-H', '--header [HEADER]',
+          'Include header with all requests') do |header|
+    parts = header.split(':', 0)
+    options[:headers][parts[0]] = parts[1].strip
+  end
+
+  opts.on('-c', '--cache-dir [PATH]',
+          'Content cache directory (~ is automatically expanded)') do |path|
+    options[:cache_path] = path.sub('~', '#{Dir.home}')
+  end
 end
 
 option_parser.parse!
-module_name, schema_filename, url = ARGV
-schema = Heroics::Schema.new(MultiJson.decode(File.read(schema_filename)))
-options = {
-  default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'},
-  cache: 'Moneta.new(:File, dir: "#{Dir.home}/.heroics/platform-api")'
-}
-puts Heroics.generate_client(module_name, schema, url, options)
+if ARGV.length != 3
+  puts option_parser
+else
+  module_name, schema_filename, url = ARGV
+  schema = Heroics::Schema.new(MultiJson.decode(File.read(schema_filename)))
+  cache = 'Moneta.new(:Memory)'
+  if options[:cache_path]
+    cache = "Moneta.new(:File, dir: \"#{options[:cache_path]}\")"
+  end
+  options = {default_headers: options[:headers], cache: cache}
+  puts Heroics.generate_client(module_name, schema, url, options)
+end

data/heroics.gemspec

@@ -10,9 +10,9 @@ Gem::Specification.new do |spec|
   spec.version       = Heroics::VERSION
   spec.authors       = ['geemus', 'jkakar']
   spec.email         = ['geemus@gmail.com', 'jkakar@kakar.ca']
-  spec.description   = 'A Ruby client for HTTP APIs described using a JSON schema'
-  spec.summary       = 'A Ruby client for HTTP APIs described using a JSON schema'
-  spec.homepage      = ''
+  spec.description   = 'A Ruby client generator for HTTP APIs described with a JSON schema'
+  spec.summary       = 'A Ruby client generator for HTTP APIs described with a JSON schema'
+  spec.homepage      = 'https://github.com/interagent/heroics'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)

data/lib/heroics/client.rb

@@ -79,4 +79,28 @@ module Heroics
     options[:default_headers].merge!({"Authorization" => authorization})
     client_from_schema(schema, url, options)
   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.
+  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
 end

data/lib/heroics/version.rb

@@ -1,3 +1,3 @@
 module Heroics
-  VERSION = '0.0.7'
+  VERSION = '0.0.8'
 end

data/lib/heroics/views/client.erb

@@ -27,8 +27,8 @@ module <%= @module_name %>
     end
     cache = <%= @cache %>
     options = {
-      options: {default_headers: default_headers,
-                cache: cache}
+      default_headers: default_headers,
+                cache: cache
     }
     client = Heroics.client_from_schema(SCHEMA, url.to_s, options)
     Client.new(client)
@@ -49,10 +49,32 @@ module <%= @module_name %>
     end
     cache = <%= @cache %>
     options = {
-      options: {default_headers: default_headers,
-                cache: cache}
+      default_headers: default_headers,
+                cache: cache
     }
-    client = Heroics.client_from_schema(oauth_token, SCHEMA, url, options)
+    client = Heroics.oauth_client_from_schema(oauth_token, SCHEMA, url, options)
+    Client.new(client)
+  end
+
+  # Get a Client configured to use Token authentication.
+  #
+  # @param token [String] The token to use with the API.
+  # @param headers [Hash<String,String>] Optionally, custom to headers to
+  #   include with every response.
+  # @return [Client] A client configured to use the API with OAuth
+  #   authentication.
+  def self.connect_token(token, headers=nil)
+    url = "<%= @url %>"
+    default_headers = <%= @default_headers %>
+    unless headers.nil?
+      default_headers.merge!(headers)
+    end
+    cache = <%= @cache %>
+    options = {
+      default_headers: default_headers,
+                cache: cache
+    }
+    client = Heroics.token_client_from_schema(token, SCHEMA, url, options)
     Client.new(client)
   end
 

data/test/client_test.rb

@@ -185,3 +185,51 @@ class OAuthClientFromSchemaTest < MiniTest::Unit::TestCase
     assert_equal(body, client.resource.list)
   end
 end
+
+class TokenClientFromSchemaTest < MiniTest::Unit::TestCase
+  include ExconHelper
+
+  # token_client_from_schema injects an Authorization header, built from the
+  # specified token, into the default header options.
+  def test_token_client_from_schema
+    body = {'Hello' => 'World!'}
+    Excon.stub(method: :get) do |request|
+      assert_equal(
+        'Token token=c55ef0d8-40b6-4759-b1bf-4a6f94190a66',
+        request[:headers]['Authorization'])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(body)}
+    end
+
+    token = 'c55ef0d8-40b6-4759-b1bf-4a6f94190a66'
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics.token_client_from_schema(token, schema,
+                                              'https://example.com')
+    assert_equal(body, client.resource.list)
+  end
+
+  # token_client_from_schema doesn't mutate the options object, and in
+  # particular, it doesn't mutate the :default_headers Hash in that object.
+  def test_token_client_from_schema_with_options
+    body = {'Hello' => 'World!'}
+    Excon.stub(method: :get) do |request|
+      assert_equal('application/vnd.heroku+json; version=3',
+                   request[:headers]['Accept'])
+      assert_equal(
+        'Token token=c55ef0d8-40b6-4759-b1bf-4a6f94190a66',
+        request[:headers]['Authorization'])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(body)}
+    end
+
+    token = 'c55ef0d8-40b6-4759-b1bf-4a6f94190a66'
+    options = {
+      default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'}}
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics.token_client_from_schema(token, schema,
+                                              'https://example.com', options)
+    assert_equal(body, client.resource.list)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: heroics
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - geemus
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-29 00:00:00.000000000 Z
+date: 2014-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -137,7 +137,7 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: A Ruby client for HTTP APIs described using a JSON schema
+description: A Ruby client generator for HTTP APIs described with a JSON schema
 email:
 - geemus@gmail.com
 - jkakar@kakar.ca
@@ -180,7 +180,7 @@ files:
 - test/resource_test.rb
 - test/schema_test.rb
 - test/version_test.rb
-homepage: ''
+homepage: https://github.com/interagent/heroics
 licenses:
 - MIT
 metadata: {}
@@ -203,5 +203,5 @@ rubyforge_project:
 rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
-summary: A Ruby client for HTTP APIs described using a JSON schema
+summary: A Ruby client generator for HTTP APIs described with a JSON schema
 test_files: []