Getting Started

​ ​Welcome

Blitline Job

Job Response

Job Options

Functions

Polling and Postbacks

Gotchas

Development Recommendations

Service Limits

Examples List

List of Available Functions

Output Options

S3 Destination

IAM Users

S3 Signed Url

Azure Destination

FTP Destination

Other Service Signed Urls

CDN

Advanced

Metadata

Colorspace

Color Extraction

Static IPs

Signed Jobs

Formats

Pipelines

Image Optimization

Smart Image

PDF

Fonts

Subimage

Special (Non-Image) Processing

AWS Rekognition/Facial Recognition

Apache Tika

Vector Processing

Animated GIFs

Screenshots of Websites

IM Scripts

Video Keyframes

Zipping

​ ​Trancoding Video Presets

​ ​Video Transcoding

Polling and Postbacks

Updated 9 days ago ​by Blitline Support

Blitline runs your jobs asynchronously, which means that after you submit your job, there will be a variable amount to time before your job has completed.

There are 2 ways for you to know that your job has completed: Postbacks and polling.

Postbacks: When the Blitline cloud machine calls your server back with JSON, thus notifying you that you job has completed.
Polling: When you ask Blitline, "is it done yet?"

 Whether you are polling or using postbacks, you will get some JSON representing the results of the job processing

The JSON returned will always have a results as the root node. Under results will be the following nodes:

REQUIRED NODES

  • images - An array of image nodes
    • image_identifier
    • destination url (such as s3_url or azure_url)
    • meta field identifying metadata about the result image - height of output image
      • width of output image
  • job_id - The unique ID associated with this particular job.
  • original_meta - Metadata about the original “src” image.
    • height of original
    • width of original.

OPTIONAL NODES

  • errors - In the event of an error during processing, this node will contain an array of Strings containing the error messages.
  • failed_image_identifiers - In the event of an error, this node will contain an array of image_identifiers that did NOT get processed.

SUCCESSFUL RESULT EXAMPLE:

{
    "results": {
        "original_meta": {
            "width": 421,
            "height": 163
        },
        "images": [
            {
                "image_identifier": "MY_CLIENT_ID",
                "s3_url": "http://s3.amazonaws.com/blitline/2014061200/20/6_wj-2i_hZRZ7KJj-jwcndQ.jpg",
                "meta": {
                    "width": 421,
                    "height": 163
                }
            }
        ],
        "job_id": "2m-Ir2YMXQ3yec0NV476xag"
    }
}

FAILED RESULT EXAMPLE:

{
    "results": {
        "original_meta": {},
        "images": [],
        "job_id": "4weK03Kd0j-D_ttohR7GTcg",
        "errors": [
            "Image processing failed. Unknown function named 'blu3r'"
        ],
        "failed_image_identifiers": [
            "MY_CLIENT_ID"
        ]
    }
}

HOW DO I GET A POSTBACK?

Postbacks are the recommended way to use Blitline. Postbacks scale as large as you want to scale. Need 8 million postbacks/hr, no problem.

You can identify you postback location by adding a postback_url to your job JSON. This url will be called as soon as the job has completed.

You can only use Postbacks OR Polling, not both. If you set a "postback_url" there will be nothing sent to our polling server.  You can optionally add "force_longpoll_cache" : true to your base JSON if you want to use BOTH Postback and Polling.

HOW DO I POLL?

Polling is great for development, and sometimes necessary in certain use cases.

Polling has rate limits though. You will not be able to poll for 8 million job_ids. In fact the current limit is 5 per second per application ID.

Show Me How  

Javascript (jquery)

$.ajax({
    url: "http://cache.blitline.com/listen/[JOB_ID]",
    success: function(data) {
        alert("Got data=" + data)
    }
});

NodeJS

var options = {
  host: 'cache.blitline.com',
  port: 80,
  path: '/listen/[JOB_ID]'
};
http.get(options, function(res) {
  res.on("data", function(chunk) {
    console.log("Data=" + chunk);
  });
})

Ruby (irb)

require 'net/http'
require 'thread'
require 'json'
Thread.new {
    url = "/listen/[JOB_ID]"
    response = Net::HTTP.get('cache.blitline.com', url)
    data = JSON.parse(response)
    puts "Data=" + data.inspect
}

Console

curl 'http://cache.blitline.com/listen/[JOB_ID]'

Simply replace [JOB_ID] with the 'job_id' you get back when you POST to the /job API.


Polling Notes
  • Prefer postbacks over long polling. Polling may fail, postbacks are guaranteed.
  • Results will only be cached for 15 minutes after end of job...get em' while they're hot!
  • Use reasonable timeouts when long polling, if you don't have a result in 30 seconds, you probably aren't going to get one.
  • Remember that if you are using a platform that blocks on http GET calls, make sure you use a thread to listen.
  • Use common sense, we have a finite number of connections for long polling. Don't deploy apps to 1M users that all use javascript long-polling. We, as always, reserve the right to rate limit or block overly heavy polling calls.

IS THERE ANY USEFUL TOOLS FOR DEBUGGING POSTBACKS?

YES! We highly recommend http://requestb.in/ . This allows you to make a free http destination url, which you can use for your postback_url

This allows you to easily inspect what Blitline is posting back to your client before you even build the client.



How did we do?