Polling and Postbacks
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.
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.
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.
- 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.