README.md in capgun-0.0.1 vs README.md in capgun-0.0.3
- old
+ new
@@ -1,5 +1,307 @@
-Capgun
-======
+# capgun.io API gem
-Place holder gem for Ruby gem that will be created to interface the capgun.io
-web thumb service.
+A Ruby wrapper for the capgun.io web thumb service API
+
+## Installation
+
+ gem install capgun
+
+## Credits
+
+The capgun's gem organization is based (and inspired!) by jnunemaker's
+[https://github.com/jnunemaker/twitter][twitter gem], see LICENSE.md.
+jnunemaker's style of coding is very elegant in its simplicity and a joy to
+read.
+
+## Configuration
+
+The gem is easy to configure with the global configure block. Its most basic
+invocation needs to set the authorization token issued to the API.
+
+```ruby
+Capgun.configure do |config|
+ config.auth_token = "YOUR-AUTH-TOKEN"
+end
+```
+
+The configuration has the following attributes to be assigned values.
+
+* adapter
+* connection_options
+* endpoint
+* gateway
+* auth_token
+* user_agent
+* proxy
+
+## Actions
+
+There are five actions exposed by the capgun gem.
+
+1. account
+1. estimate
+1. capture
+1. status
+1. order
+
+## account
+
+Fetches the account owner's information.
+
+```ruby
+# returns a Capgun::Account object
+account = Capgun.account
+# attributes: id, :name, :balance
+account.balance
+```
+
+example JSON responses from the capgun service.
+
+```shell
+curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/account'
+```
+
+```json
+{
+ "account": {
+ "id": "vexuq9ff",
+ "name": "Acme Co.",
+ "notify": "http://example.com/notify",
+ "balance": 200,
+ "created_at": "2012-06-08T05:55:39+00:00",
+ "updated_at": "2012-06-08T05:55:39+00:00"
+ }
+}
+```
+
+
+## estimate
+
+An estimate is an order that has not been executed. It lists the assets that
+will be delivered in the order and its cost.
+
+```ruby
+# returns a Capgun::Order object
+estimate = Capgun.estimate("http://www.google.com/")
+# attributes: url, notify, cost, viewport, packages, images, options
+estimate.cost
+```
+
+example JSON responses from the capgun service.
+
+```shell
+curl -H 'Authorization: abc123' \
+ --data '{"url":"http://rubygems.org/"}' \
+ 'https://api.capgun.io/v1/orders/estimate.json'
+```
+
+```json
+{
+ "order": {
+ "url": "http://rubygems.org/",
+ "notify": null,
+ "cost": 1,
+ "viewport": "1024x768",
+ "images": {
+ "xlarge": "640x480"
+ },
+ "packages": [
+ "base"
+ ],
+ "options": [
+ {
+ "package": "base"
+ },
+ {
+ "url": "http://rubygems.org/"
+ },
+ {
+ "notify": null
+ },
+ {
+ "timeout": 5000
+ },
+ {
+ "viewport": "1024x768"
+ },
+ {
+ "image": {
+ "xlarge": "640x480"
+ }
+ }
+ ]
+ }
+}
+```
+
+
+## capture
+
+Capture executes an order. The order object lists the assets that will be
+delivered in the order, the order's cost, and the job representing the order.
+
+```ruby
+# returns a Capgun::Order object
+order = Capgun.capture("http://www.google.com/")
+# attributes: id, url, notify, cost, viewport, packages, images, asset_urls, options, job
+order.viewport
+```
+
+example JSON responses from the capgun service.
+
+```shell
+curl -H 'Authorization: abc123' \
+ --data '{"url":"http://rubygems.org/"}' \
+ 'https://api.capgun.io/v1/orders.json'
+```
+
+```json
+{
+ "order": {
+ "created_at": "2013-04-17T20:23:29-07:00",
+ "url": "http://rubygems.org/",
+ "notify": null,
+ "cost": 1,
+ "viewport": "1024x768",
+ "images": {
+ "xlarge": "640x480"
+ },
+ "packages": [
+ "base"
+ ],
+ "id": "u1qj2mz1",
+ "options": [
+ {
+ "package": "base"
+ },
+ {
+ "url": "http://rubygems.org/"
+ },
+ {
+ "notify": null
+ },
+ {
+ "timeout": 5000
+ },
+ {
+ "viewport": "1024x768"
+ },
+ {
+ "image": {
+ "xlarge": "640x480"
+ }
+ }
+ ],
+ "job": {
+ "state": "initialized",
+ "transition": "capturing",
+ "id": "qy9ujcly"
+ }
+ }
+}
+```
+
+
+## status
+
+Status is a lighter call to get the status of an order.
+
+```ruby
+# returns a Capgun::Job object
+job = Capgun.status("qy9ujcly")
+# attributes: id, state, order_id
+job.state
+```
+
+example JSON responses from the capgun service.
+
+```shell
+curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/jobs/qy9ujcly'
+```
+
+```json
+{
+ "job": {
+ "state": "initialized",
+ "transition": "capturing",
+ "created_at": "2013-04-17T20:23:29-07:00",
+ "id": "qy9ujcly",
+ "order_id": "u1qj2mz1"
+ }
+}
+```
+
+
+## order
+
+Fetches an existing order object and lists the assets that it delivers in the
+order, the order's cost, and the job representing the order.
+
+```ruby
+# returns a Capgun::Order object
+order = Capgun.order("u9qj2mc9")
+# attributes: url, notify, cost, viewport, packages, images, options
+order.asset_urls
+order.asset_urls["xlarge"]
+order.asset_urls["package"]
+```
+
+example JSON responses from the capgun service.
+
+```shell
+curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/orders/u9qj2mc9'
+```
+
+```json
+{
+ "order": {
+ "created_at": "2013-02-17T22:45:20-08:00",
+ "url": "http://rubygems.org/",
+ "notify": null,
+ "cost": 1,
+ "viewport": "1024x768",
+ "images": {
+ "xlarge": "640x480"
+ },
+ "asset_urls": {
+ "xlarge": "https://api.capgun.io/v1/orders/u9qj2mc9/640x480.png",
+ "package": "https://api.capgun.io/v1/orders/u9qj2mc9/package.zip"
+ },
+ "packages": [
+ "base"
+ ],
+ "id": "u9qj2mc9",
+ "options": [
+ {
+ "package": "base"
+ },
+ {
+ "url": "http://rubygems.org/"
+ },
+ {
+ "notify": null
+ },
+ {
+ "timeout": 5000
+ },
+ {
+ "viewport": "1024x768"
+ },
+ {
+ "image": {
+ "xlarge": "640x480"
+ }
+ }
+ ],
+ "job": {
+ "state": "completed",
+ "transition": "complete",
+ "queued": 1.2787141799926758,
+ "capturing": 25.210319995880127,
+ "processing": 4.529249906539917,
+ "duration": 31.01828408241272,
+ "id": "5dlj5i1u"
+ }
+ }
+}
+```