capgun.io API gem

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.

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
  2. estimate
  3. capture
  4. status
  5. order

account

Fetches the account owner's information.

# returns a Capgun::Account object
 = Capgun.
# attributes: id, :name, :balance
.balance

example JSON responses from the capgun service.

curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/account'
{
  "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.

# 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.

curl -H 'Authorization: abc123' \
     --data '{"url":"http://rubygems.org/"}'  \
     'https://api.capgun.io/v1/orders/estimate.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.

# 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.

curl -H 'Authorization: abc123' \
     --data '{"url":"http://rubygems.org/"}'  \
     'https://api.capgun.io/v1/orders.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.

# returns a Capgun::Job object
job = Capgun.status("qy9ujcly")
# attributes: id, state, order_id
job.state

example JSON responses from the capgun service.

curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/jobs/qy9ujcly'
{
  "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.

# 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.

curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/orders/u9qj2mc9'
{
  "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"
    }
  }
}