Getting Started

Introduction

Welcome to uploadJuicer! Our purpose in life is to offer you an easy way
to add scalable image processing to your application.

Let's get started!

API Keys

You have a unique API key that should be sent along with every API request.

If you were logged in, we'd show you your API key here, and insert it
into the code below. But since you're not, we'll use this placeholder: [ Your Single Access Token ].

Requests

All API requests are made by posting JSON. Here's the simplest possible request:

curl --data '{"url":"http://farm3.static.flickr.com/2084/2222523486_5e1894e314.jpg", "outputs":[{"resize":"100x100>"}]}' \
"http://app.uploadjuicer.com/jobs?token=[ Your Single Access Token ]" \
-H 'Content-Type: application/json' -H 'Accept: application/json'

Responses

You'll get back a JSON response that includes the ID of your job, and the result of the job being queued. This status doesn't mean the processing was completed successfully (or at all), just that the job was queued (or not):

{
  "id"=>"ccf8c68dcb4e8c6d1a66e14ff67c9663", 
  "url"=>"http://farm3.static.flickr.com/2084/2222523486_5e1894e314.jpg", 
  "outputs"=>[{"resize"=>"100x100>"}], 
  "status"=>"queued"
}

Querying Job Details

You can use that id to query the status of the job later to find out when it is finished and to get the URLs of the output files:

curl "http://app.uploadjuicer.com/jobs/ccf8c68dcb4e8c6d1a66e14ff67c9663?token=[ Your Single Access Token ]" \
-H 'Content-Type: application/json' -H 'Accept: application/json'

{
  "id":"ccf8c68dcb4e8c6d1a66e14ff67c9663", 
  "url":"http://farm3.static.flickr.com/2084/2222523486_5e1894e314.jpg", 
  "outputs":[
    {
      "resize":"100x100>",
      "url":"http://deliveries.uploadjuicer.com.s3.amazonaws.com/7006/d28c/060d/1eda/2222523486_5e1894e314.jpg"
    }
  ], 
  "status":"finished"
}

As you can see, if you don't specify any outputs, Juicer will store the files for you on S3 as world-readable. These files will be available for about a day before they are deleted.

Getting Notifications

If you'd like to be notified when a job has been completed, specify a URL to receive a POST request:

curl --data '{"notification":"http://example.com/job_done", "url":"http://farm3.static.flickr.com/2084/2222523486_5e1894e314.jpg", "outputs":[{"resize":"100x100>"}]}' \
"http://app.uploadjuicer.com/jobs?token=[ Your Single Access Token ]" \
-H 'Content-Type: application/json' -H 'Accept: application/json'

In this example, you would get a POST to http://example.com/job_done with the same JSON shown in the Querying Job Details section, with the addition of signature info (an HMAC 256 signature). The POST will be sent with the Content-Type: application/json and Accept: application/json headers, so in Rails apps you would see the parameters id, url, outputs, and status for the job info, and the parameters auth_timestamp, auth_key, auth_version, and auth_signature for the signature.

Your API Key and your Secret Key (available here) are used to generate the signature, and the signature gem can be used to verify it. The signature is generated with the request method (POST), the URL you specified as the notification target, and the hash that gets JSON-encoded and posted to your URL.

Are you a fan of Ruby?

We are too, and you can check out the gem at GitHub. Alternatively, you can use the RestClient gem like so:

JSON.parse(
  RestClient.post('https://app.uploadjuicer.com/jobs?token=[ Your Single Access Token ]',
    { 
      :url => "http://farm3.static.flickr.com/2084/2222523486_5e1894e314.jpg",
      :outputs => [{"resize" => "100x100>"}]
    }.to_json, 
    { 
      :content_type => :json, 
      :accept => :json 
    }
  )
)  

Leveraging S3

You can specify your own destination URLs as S3 locations:

  curl --data '{"url":"http://farm3.static.flickr.com/2084/2222523486_5e1894e314.jpg", "outputs":[{"resize":"100x100>", "url":"s3://mybucket/my/path/to/output/file.jpg"}]}' \
  "http://app.uploadjuicer.com/jobs?token=[ Your Single Access Token ]" \
  -H 'Content-Type: application/json' -H 'Accept: application/json'

When you specify output URLs, those URLs show up in the JSON returned when queuing the job. For this to work, you'll need to grant access
to Juicer to write to your bucket.

Juicer's S3 ID is
908c0730af6ca2cce67d570b1aac1c9da18a53007effa7b52c3145ffe249edc5

Files stored in your bucket will be stored with the "public read" ACL, and the
FULL_CONTROL permission will be granted to the bucket owner. You can specify
an S3 URL as the source URL, too, if Juicer can access the file (the file is
either world-readable or Juicer has read permissions on the file).

curl --data '{"url":"s3://mybucket/my/path/to/input/file.jpg", "outputs":[{"resize":"100x100>", "url":"s3://mybucket/my/path/to/output/file.jpg"}]}' \
"http://app.uploadjuicer.com/jobs?token=[ Your Single Access Token ]" \
-H 'Content-Type: application/json' -H 'Accept: application/json'

Here's a bucket access policy you can use to grant UploadJuicer access to your bucket:

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "AddCannedAcl",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::535855700800:root"
      },
      "Action": [
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:PutObject",
        "s3:GetBucketAcl",
        "s3:GetObjectAcl"
      ],
      "Resource": [
        "arn:aws:s3:::yourbucketname",
        "arn:aws:s3:::yourbucketname/*"
      ]
    }
  ]
}

More Info

You can pass other info in the outputs hashes, like labels, your own ids, or whatever. That extra info will be passed back to you in the response JSON.

If you have questions about using the API, please contact us at
support@uploadjuicer.com