RubyGems - heroics - Versions diffs - 0.0.1 → 0.0.2 - Mend

heroics 0.0.1 → 0.0.2

Files changed (9) hide show

data/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Heroics
-TODO: Write a gem description
+Ruby HTTP client for APIs represented with JSON schema.
 ## Installation
@@ -18,36 +18,187 @@ Or install it yourself as:
 ## Usage
-TODO: Write usage instructions here
+### Generate a client from a JSON schema
-The interface is designed to match the workings of the (Heroku Platform API)[https://devcenter.heroku.com/articles/platform-api-reference].
+Heroics generates an HTTP client from a JSON schema.  The simplest way
+to get started is to provide the URL to the schema you want to base
+the client on:
+```ruby
+require 'cgi'
+require 'heroics'
+username = CGI.escape('username')
+token = 'token'
+url = "https://#{username}:#{token}@api.heroku.com/schema"
+options = {default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'}}
+client = Heroics.client_from_schema_url(url, options)
+```
+The client will make requests to the API using the credentials from
+the URL.  The default headers will also be included in all requests
+(including the one to download the schema and all subsequent
+requests).
+You can also create a client from an in-memory schema object:
+```ruby
+require 'cgi'
+require 'json'
+require 'heroics'
+username = CGI.escape('username')
+token = 'token'
+url = "https://#{username}:#{token}@api.heroku.com/schema"
+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)
+```
+### Client-side caching
+Heroics handles ETags and will cache data on the client if you provide
+a [Moneta](https://github.com/minad/moneta) cache instance.
+```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")}
+client = Heroics.client_from_schema_url(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
+```
+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
+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")}
+cli = Heroics.cli_from_schema_url('heroku-api', STDOUT, 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:
+```ruby
+client.app.create({'name'   => 'example',
+                   'region' => '',
+                   'stack'  => ''})
+```
+### Command arguments
+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.
 ```
-heroics = Heroics.new(token: ENV['HEROKU_API_TOKEN'])
-# apps
-heroics.apps.create(name: 'example')  # returns new app named 'example'
-heroics.apps.list                     # returns list of all apps
-heroics.apps.info('example')          # returns app with id or name of 'example'
+This command needs an app's UUID or name:
+```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).
-app = heroics.apps('example')       # returns local reference to app with id or name 'example'
-app.update(name: 'rename')          # returns updated app
-app.delete                          # returns deleted app
+### Handling failures
-# addons
-app = heroics.apps('example')                               # returns local reference to app with id or name 'example'
-app.addons.create(plan: { name: 'heroku-postgresql:dev' })  # returns new add-on with plan:name 'heroku-postgresql:dev'
-app.addons.list                                             # returns list of all add-ons for app with id or name of 'example'
+The client uses [Excon](https://github.com/geemus/excon) under the hood and raises Excon errors when
+failures occur.
-addon = app.addons.info('heroku-postgresql:dev')            # returns add-on with id or name 'heroku-postgresql:dev'
-addon.update(plan: { name: 'heroku-postgresql:basic' })     # returns updated add-on
-addon.delete                                                # returns deleted add-on
+```ruby
+begin
+  client.app.create({'name' => 'example'})
+rescue Excon::Errors::Forbidden => e
+  puts e
+end
 ```
 ## Contributing
-1. Fork it
+1. [Fork the repository](https://github.com/heroku/heroics/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Create new pull request

data/lib/heroics.rb CHANGED Viewed

@@ -8,6 +8,7 @@ require 'zlib'
 module Heroics
 end
+require 'heroics/version'
 require 'heroics/errors'
 require 'heroics/naming'
 require 'heroics/link'

data/lib/heroics/cli.rb CHANGED Viewed

@@ -61,8 +61,21 @@ USAGE
     end
   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.
   def self.cli_from_schema(name, output, schema, url, options={})
-    client = client_from_schema(schema, url, options)
+    client = client_from_schema(schema, URI::join(url, '/').to_s, options)
     commands = {}
     schema.resources.each do |resource_schema|
       resource_schema.links.each do |link_schema|

data/lib/heroics/client.rb CHANGED Viewed

@@ -15,8 +15,12 @@ module Heroics
     # @raise [NoMethodError] Raised if the name doesn't match a known resource.
     # @return [Resource] The resource matching the name.
     def method_missing(name)
+      name = name.to_s.gsub('_', '-')
       resource = @resources[name.to_s]
       if resource.nil?
+        # TODO(jkakar) Do we care about resource names in the schema specified
+        # with underscores?  If so, we should check to make sure the name
+        # mangling we did above was actually a bad idea.
         address = "<#{self.class.name}:0x00#{(self.object_id << 1).to_s(16)}>"
         raise NoMethodError.new("undefined method `#{name}' for ##{address}")
       end

data/lib/heroics/link.rb CHANGED Viewed

@@ -13,7 +13,7 @@ module Heroics
     #   - cache: Optionally, a Moneta-compatible cache to store ETags.
     #     Default is no caching.
     def initialize(url, link_schema, options={})
-      @url = url
+      @root_url, @path_prefix = unpack_url(url)
       @link_schema = link_schema
       @default_headers = options[:default_headers] || {}
       @cache = options[:cache] || Moneta.new(:Null)
@@ -44,6 +44,7 @@ module Heroics
     #   object for JSON responses, or an enumerator for list responses.
     def run(*parameters)
       path, body = @link_schema.format_path(parameters)
+      path = "#{@path_prefix}#{path}" unless @path_prefix == '/'
       headers = @default_headers
       if body
         headers = headers.merge({'Content-Type' => 'application/json'})
@@ -55,7 +56,7 @@ module Heroics
         headers = headers.merge({'If-None-Match' => etag}) if etag
       end
-      connection = Excon.new(@url)
+      connection = Excon.new(@root_url)
       response = connection.request(method: @link_schema.method, path: path,
                                     headers: headers, body: body,
                                     expects: [200, 201, 202, 206, 304])
@@ -96,5 +97,24 @@ module Heroics
         response.body
       end
     end
+    private
+    # Unpack the URL and split it into a root URL and a path prefix, if one
+    # exists.
+    #
+    # @param url [String] The complete base URL to use when making requests.
+    # @return [String,String] A (root URL, path) prefix pair.
+    def unpack_url(url)
+      root_url = []
+      path_prefix = ''
+      parts = URI.split(url)
+      root_url << "#{parts[0]}://"
+      root_url << "#{parts[1]}@" unless parts[1].nil?
+      root_url << "#{parts[2]}"
+      root_url << ":#{parts[3]}" unless parts[3].nil?
+      path_prefix = parts[5]
+      return root_url.join(''), path_prefix
+    end
   end
 end

data/lib/heroics/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module Heroics
-  VERSION = "0.0.1"
+  VERSION = '0.0.2'
 end

data/test/cli_test.rb CHANGED Viewed

@@ -188,6 +188,29 @@ class CLIFromSchemaTest < MiniTest::Unit::TestCase
     assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
   end
+  # cli_from_schema returns a CLI that can make requests to APIs mounted under
+  # a prefix, such as http://example.com/api, for example.
+  def test_client_from_schema_with_url_prefix
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    body = {'Hello' => 'World!'}
+    result = {'Goodbye' => 'Universe!'}
+    Excon.stub(method: :patch) do |request|
+      assert_equal("/api/resource/#{uuid}", request[:path])
+      assert_equal('application/json', request[:headers]['Content-Type'])
+      assert_equal(body, MultiJson.load(request[:body]))
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    output = StringIO.new
+    cli = Heroics.cli_from_schema('cli', output, schema,
+                                  'https://example.com/api')
+    cli.run('resource:update', uuid, body)
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
   # cli_from_schema optionally accepts custom headers to pass with every
   # request made by the generated CLI.
   def test_cli_from_schema_with_custom_headers

data/test/client_test.rb CHANGED Viewed

@@ -33,6 +33,26 @@ class ClientTest < MiniTest::Unit::TestCase
     end
     assert_equal('Hello, world!', client.resource.link)
   end
+  # Client converts underscores in resource method names to dashes to match
+  # names specified in the schema.
+  def test_resource_with_dashed_name
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    link = Heroics::Link.new('https://username:secret@example.com',
+                             schema.resource('another-resource').link('list'))
+    resource = Heroics::Resource.new({'link' => link})
+    client = Heroics::Client.new({'another-resource' => resource})
+    Excon.stub(method: :get) do |request|
+      assert_equal('Basic dXNlcm5hbWU6c2VjcmV0',
+                   request[:headers]['Authorization'])
+      assert_equal('example.com', request[:host])
+      assert_equal(443, request[:port])
+      assert_equal('/another-resource', request[:path])
+      Excon.stubs.pop
+      {status: 200, body: 'Hello, world!'}
+    end
+    assert_equal('Hello, world!', client.another_resource.link)
+  end
 end
 class ClientFromSchemaTest < MiniTest::Unit::TestCase
@@ -52,6 +72,21 @@ class ClientFromSchemaTest < MiniTest::Unit::TestCase
     assert_equal(body, client.resource.create)
   end
+  # client_from_schema returns a Client that can make requests to APIs mounted
+  # under a prefix, such as http://example.com/api, for example.
+  def test_client_from_schema_with_url_prefix
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com/api')
+    body = {'Hello' => 'World!'}
+    Excon.stub(method: :post) do |request|
+      assert_equal('/api/resource', request[:path])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(body)}
+    end
+    assert_equal(body, client.resource.create)
+  end
   # client_from_schema optionally accepts custom headers to pass with every
   # request made by the generated client.
   def test_client_from_schema_with_custom_headers

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: heroics
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease:
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-12-16 00:00:00.000000000 Z
+date: 2014-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -193,7 +193,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 761301083637383534
+      hash: 1762076871697657264
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -202,7 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 761301083637383534
+      hash: 1762076871697657264
 requirements: []
 rubyforge_project:
 rubygems_version: 1.8.23