An API tester tool is available for learning the API. It makes requests using XMLHttpRequest, but that won't work for your own usage because of JavaScript's security restrictions.
The API end-point is http://webthumb.bluga.net/api.php
Requests are made by sending XML to the end point as POST requests.
These is different then a POST request sent by a browser which are application/x-www-form-urlencoded or multipart/form-data encoded. Your just sending the XML as the request body.
You likely want to use the new style error handling, it lets you use http response codes and gives you errors as xml.
Response is content-type: text/xml on success, and text/plain with a error message on failure
Currently failure conditions when making multiple requests (and some are Ok) aren't handled well. You'll get a non specific error message at the end of the XML.
XML Parse errors are always handled with the new style error handling, for all other methods you need to add a version flag. Version 3 gives you xml response codes and http status codes, Version 2 gives you xml response codes but always an http 200. Version 3 also gives you errors per request, see Getting submission errors for details.
<webthumb> <version>3</version> <request> ... </request> </webthumb>
Common causes of errors are:
In version 3 you can expect an HTTP 500 status code for errors. The error message is is included in an error element. An example from invalid XML is shown below, an EntityRef error is the most common, its caused by not escaping & in urls.
<webthumb> <error type='xml' level='3' line='6' column='41'>EntityRef: expecting ';'</error> </webthumb>
You may also see internal errors in a partial outage situation, it is useful to send these error when reporting bugs. You can add a throw_internal_error tag to test handling this error type. Example:
<webthumb> <error type='internal' code='2'>Division by zero</error> </webthumb>
XML requests are all under the webthumb root node, request types include:
Every request starts by setting your apikey, you can get the key from your user page.
<webthumb> <apikey>apikey here</apikey> </webthumb>
Thumbnails requests are made within the request node. You can submit as many requests as you want at a time, but its recommend to send less then 100 in each request since validation can easily take 1 second per request.
Under the request node you can set a number of options, only url is required.
By default requests give you 5 thumbnails, these are available individually or in a zip file
Aspect ratio is always kept for small, medium, medium2, and large thumbnails so the height will change with non standard browser sizes.
3 optional thumbnails are also available
Options
x, y, width, height
An example setting all options is shown below
<webthumb> <version>3</version> <apikey>apikey here</apikey> <request> <url>webthumb.bluga.net</url> <outputType>png</outputType> <width>1280</width> <height>1024</height> <fullthumb>1</fullthumb> <customThumbnail width="120" height="120" /> <effect>mirror</effect> <delay>5</delay> <excerpt> <x>400</x> <y>400</y> <height>200</height> <width>200</width> </excerpt> <notify>http://webthumb.bluga.net/notify.php</notify> </request> </webthumb>
The response of a request include one job element per request element. Each job element includes the follow information as attributes
The value of the job element is the "job id", unless your using notify or url lookups you'll want to store this for fetch and status calls
<webthumb> <jobs> <job estimate='20' time='2008-02-27 16:49:48' url='http://blog.joshuaeichorn.com' cost='1'>wt47c5f71c37c3a</job> <job estimate='38' time='2008-02-27 16:49:48' url='http://webthumb.bluga.net' cost='2'>wt47c5f71c3b6d2</job> </jobs> </webthumb>
Except for out of credits or invalid options (specifying an non-existant effect etc) you will always get an a standard response from a request submission.
Make sure to handle the out of credit case, if you are using webthumb as part of an automated process.
<webthumb> <error type='request'>Max number of thumbnail requests (100) already made this month, purchase credits to make more requests</error> </webthumb>
If you are using version 3 or greater error handling you will get an additional errors block which contains per request errors.
<webthumb> <errors> <error url='webthumb.bluga.neta'>Bar Url</error> </errors> </webthumb> <webthumb> <jobs> <job estimate='20' time='2010-07-28 22:29:23' url='http://webthumb.bluga.net' cost='2'>wt4c5111b31c585</job> </jobs> <errors> <error url='webthumb.bluga.neta'>Bar Url</error> </errors> </webthumb>
With Webthumb you can poll for status or use the Notify callback mechanism. For non interactive tools the perfered approach is the notify callback.
On the completion of your thumbnail a GET request will be sent to the url specified in the notify tag in the request. You can include any GET parameters in the request that you want, its common to include your local identify of the thumbnail. The url that was request and the Webthumb job id will also be included in the notify callback.
For more details please see the article covering a PHP implmentation of the notify callback.
You can now switch notify to POST, just add post="true" to your notify request, an example would be.
<webthumb>
<apikey>apikey here</apikey>
<request>
<url>http://webthumb.bluga.net</url>
<notify post="true">http://webthumb.bluga.net/notify.php</notify>
</request>
</webthumb>
Status requests allow you to tell when a job has been completed and you can download your thumbnails.
You don't have to make status requests but you'll need to handle errors when fetching if you don't.
You can check the status of multiple jobs at once, try to combine these requests and make sure not to make more then 1 status request per second. More requests then that may get you temporarily blocked at the firewall. Best Practice is to make a status request at most every 10 seconds
If your planning on making more then 500 thumbnail requests a day please looking into using notifications instead of polling for status
There are 3 ways to make a status request, with a job id, with a url, or a general status request that returns status on your last 100 jobs.
You can request status on as many jobs at once as you want
<webthumb> <apikey>apikey here</apikey> <status> <job>wt47c5fcba65776</job> <job>wt44f5bf42a0e4a</job> <job>wt44f5bf42a202f</job> </status> </webthumb>
In a url request a search is done against the specified url with the most recent job with a matching url being used.
<webthumb> <apikey>apikey here</apikey> <status> <url>webthumb.bluga.net</url> <url>slashdot.org</url> </status> </webthumb>
<webthumb> <apikey>apikey here</apikey> <status/> </webthumb>
All request types return the same type of response
<webthumb> <jobStatus> <status id='wt47c5fcba65776' submissionTime='2008-02-27 17:13:46' browserWidth='1024' browserHeight='768' inProcess='1' ></status> <status id='wt47c5f71c37c3a' submissionTime='2008-02-27 16:49:48' browserWidth='1024' browserHeight='768' pickup='http://webthumb.bluga.net/data/3a/7c/c3/wt47c5f71c37c3a.zip' completionTime='2008-02-27 16:50:01'>Complete</status> <status id='wt47c5f71c3b6d2' submissionTime='2008-02-27 16:49:48' browserWidth='1280' browserHeight='1024' pickup='http://webthumb.bluga.net/data/d2/b6/c3/wt47c5f71c3b6d2.zip' completionTime='2008-02-27 16:50:06'>Complete</status> </jobStatus> </webthumb>
The result includes the follow fields:
If a job is completed the element will have a value of Complete it will also have a completionTime attribute
You can fetch thumbnails using the API or directly using the pickup url specified in the status call. The pickup url pattern won't change without notice so you can generate the url directly from a submit result if you want.
The fetch API call has 2 types, job id and url. Be prepared for an error message of Waiting on job completion if you haven't already verified the the job is complete with a status call.
You can only fetch one file at once, though you can fetch zip files which will allow you get all the generated thumbnails in one download.
<webthumb> <apikey>apikey here</apikey> <fetch> <job>wt47c5f71c3b6d2</job> <size>small</size> </fetch> </webthumb>
<webthumb> <apikey>apikey here</apikey> <fetch> <url>slashdot.org</url> <size>zip</size> </fetch> </webthumb>
Possible fetch sizes are the same names as the request sizes.
This section covers version 2 of higher error handling though the concepts apply for v1 handling as well.
Errors are returned for non-existant job ids, sizes, or if the job hasn't completed.
Invalid JobId<webthumb> <error type='request'>Bad JobId</error> </webthumb>Bad Size
<webthumb> <error type='request'>Unknown Size</error> </webthumb>Valid size but the file doesn't exist (size wasn't made)
<webthumb> <error type='internal' code='2'>filesize(): stat failed for /home/htdocs/jeichorn/webthumb.bluga.net/data/85/c5/31/wt4c5111b31c585-thumb_custom.png</error> </webthumb>Job isn't complete
<webthumb> <error type='request'>Waiting on job completion</error> </webthumb>
A credit status request lets you see how many credits you've used and how many subscription/reserve credits you have left.
<webthumb>
<apikey>apikey here</apikey>
<credits />
</webthumb>
The request will give you a response with 4 elements:
<webthumb> <credits> <used-this-month>1642.5</used-this-month> <easythumb-cached-this-month>15765</easythumb-cached-this-month> <subscription>1000</subscription> <reserve>45587.1</reserve> </credits> </webthumb>
Most requests cost 1 credit, some options increase the cost to 2 credits. Once you use one 2 credit feature the others are available without any additional costs.
2 Credit Features:
Feel free to email us with any questions, or feedback