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.
