Learning the API

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.

End Point

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.

Error handling

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.

New Error handling

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:

  • Invalid api key
  • Invalid XML
  • Invalid urls or nonexistant hostnames on requests
  • Using non-existant options to a request
  • Fetching non-existant files or jobs that aren't complete

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 Payload

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>

Submitting a Request

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

  • small - 80x60
  • medium - 160x120
  • medium2 - 320x240
  • large - 640x480
  • excerpt - 400x150 (taken from the top left corner by default)

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

  • full - the size of the browser
  • custom - whatever size you specify
  • effect - Size depends on the effect, 300x250 base size (image type is always png)

Options

  • url - The url to snapshot
  • outputType - The image output type (jpg|png|png8)
  • width - Width of the browser, 15 to 1280
  • height - Height of the browser, 15 to 2048
  • fullthumb - Output a full sized snapshot (1|0)
  • customThumbnail - 2 attributes width, height (1 to browser height), width (1 to browser width)
  • effect - Visual effect thumbnail to produce (mirror|dropshadow|border
  • delay - Wait before taking the snapshot (1 to 15 seconds, 3 second default)
  • notify - Url to call when the thumbnail is complete, an article is available with details
  • excerpt - Size and offset of the excerpt thumnbnail, has 4 sub elements 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>

Request result

The response of a request include one job element per request element. Each job element includes the follow information as attributes

  • estimate - Number of seconds until the job might be complete, its best practice to wait at least half this length until checking for job completion. Note that this estimate isn't that accurate when the system is very busy.
  • time - The submission time of the job (The timezone is MST)
  • url - The requested url
  • cost - The # of credits this job cost

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>

Request Errors

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>

Handling Notify Requests

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.

NEW FEATURE - POST notify requests

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

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.

Job id request

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>

Url request

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>

Generic Status Request

<webthumb>
	<apikey>apikey here</apikey>
	<status/>
</webthumb>

Response

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:

  • id - The job id
  • submissionTime - The time the job was submitted
  • browserWidth - Width of the browser that was used
  • browserHeight - Height of the browser that was used
  • pickup - Url where you can directly download a zip file with all the images
  • completionTime - Time when the job was completed
  • inProcess - Boolean if the thumbnail is currently being generated

If a job is completed the element will have a value of Complete it will also have a completionTime attribute

Fetch Requests

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.

Job id Style request

<webthumb>
	<apikey>apikey here</apikey>
	<fetch>
		<job>wt47c5f71c3b6d2</job>
		<size>small</size>
	</fetch>
</webthumb>

Url Style request

<webthumb>
	<apikey>apikey here</apikey>
	<fetch>
		<url>slashdot.org</url>
		<size>zip</size>
	</fetch>
</webthumb>

Sizes

Possible fetch sizes are the same names as the request sizes.

  • small
  • medium
  • medium2
  • large
  • full
  • excerpt
  • effect
  • custom
  • zip

Fetch Requests Errors

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>

Credit Status

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:

  • used-this-month: The # of credits used this month, this should be a whole # unless your using easythumb
  • easythumb-cached-this-month: The # of cached thumbnails served by easythumb this month
  • subscription: The # of subscription credits you get each month (100 for most people)
  • reserve: The # of non-expiring credits you've purcahsed and haven't used
<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>

Thumbnail costs

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:

  • Custom Sized Thumbnails (larger then 250 pixels in height or width)
  • PNG output (PNG32 only PNG8 costs 1 credit)
  • Browser height greater then 1024
  • Full browser size thumbnail output
  • Thumbnail visual effects
  • Excerpts larger then 800 wide or 600 high

Getting Support

Feel free to email us with any questions, or feedback