API Documentation


This page describes all the requests avaible in the current version: v1 online since 26/Jul/2012


How it works

Our API flow after receiving a new request:

  1. Parse the request and download the original image.
  2. Apply transformations or get data (e.g.: EXIF) from the image.
  3. Save the new transformed image or data (e.g.: EXIF) in our cache.
  4. Send new transformed image or JSON document.

After the first request we will always send the cached version, even if the original image is no longer online. To force an image to be processed again just add the version parameter to the request URL (check docs bellow on how to do that).


Entry Point

All requests start with http://api.rethumb.com/v1/ and have the following format:

http://api.rethumb.com/v1/<parameter_1>/<value_1>/<url>
http://api.rethumb.com/v1/<parameter_1>/<value_1>/<parameter_2>/<value_2>/<url>

Requests

The following parameters can be used.

Square

This will return a centered square thumbnail from the original image, cropping when needed.


Parameters


square - width of the thumbnail in pixels (height and width will be equal) Mandatory

version - An alphanumeric value that represents the version of the image. When changed the API will process the image again. Optional

url - URL of the image to process (this parameter doesn't have a name, only value; HTTPS is supported; JPEG, GIF, PNG or TIFF files only) Mandatory


Return

This will return a HTTP status code 200 and an image with the same MIME type of the processed image. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.


Examples


http://api.rethumb.com/v1/square/175/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/square/175/version/xc98/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/square/175/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/square/175/version/xc98/http://images.rethumb.com/image_coimbra_600x600.jpg

Width

This will return a thumbnail of the given width (image ratio is kept).


Parameters


width - width of the thumbnail in pixels Mandatory

version - An alphanumeric value that represents the version of the image. When changed the API will process the image again. Optional

url - URL of the image to process (this parameter doesn't have a name, only value; HTTPS is supported; JPEG, GIF, PNG or TIFF files only) Mandatory


Return

This will return a HTTP status code 200 and an image with the same MIME type of the processed image. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.


Examples


http://api.rethumb.com/v1/width/250/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/250/version/xc38/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/250/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/width/250/version/xc38/http://images.rethumb.com/image_coimbra_600x600.jpg

Height

This will return a thumbnail of the given height (image ratio is kept).


Parameters


height - height of the thumbnail in pixels Mandatory

version - An alphanumeric value that represents the version of the image. When changed the API will process the image again. Optional

url - URL of the image to process (this parameter doesn't have a name, only value; HTTPS is supported; JPEG, GIF, PNG or TIFF files only) Mandatory


Return

This will return a HTTP status code 200 and an image with the same MIME type of the processed image. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.


Examples


http://api.rethumb.com/v1/height/250/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/height/250/version/xc38/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/height/250/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/height/250/version/xc38/http://images.rethumb.com/image_coimbra_600x600.jpg

Width and Height

This will return a thumbnail of the given width or height (image ratio is kept, the smallest dimension is used).


Parameters


width - width of the thumbnail in pixels Mandatory

height - height of the thumbnail in pixels Mandatory

version - An alphanumeric value that represents the version of the image. When changed the API will process the image again. Optional

url - URL of the image to process (this parameter doesn't have a name, only value; HTTPS is supported; JPEG, GIF, PNG or TIFF files only) Mandatory


Return

This will return a HTTP status code 200 and an image with the same MIME type of the processed image. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.


Examples


http://api.rethumb.com/v1/width/100/height/250/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/100/height/250/version/xc38/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/100/height/250/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/width/100/height/250/version/xc38/http://images.rethumb.com/image_coimbra_600x600.jpg

EXIF

This will return a JSON document with the EXIF info of the image.


Parameters


exif - EXIF Tag ID to return a specifc value or 'all' to get all EXIF info available. Mandatory

version - An alphanumeric value that represents the version of the image. When changed the API will process the image again. Optional

url - URL of the image to process (this parameter doesn't have a name, only value, HTTPS is supported) Mandatory


Return

This will return a HTTP status code 200 with a JSON document. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.


Examples


http://api.rethumb.com/v1/exif/110/http://images.rethumb.com/image_exif_1.jpg
http://api.rethumb.com/v1/exif/all/http://images.rethumb.com/image_exif_1.jpg

Errors

API requests that result in a error will return:
- HTTP Status code 400;
- PNG image with a error message and error code;
- Custom HTTP header with a error message and error code: rethumb-error-message.

Error Example:

http://api.rethumb.com/v1/height/9999//http://factor45.org/images/beach.jpg

Custom HTTP header:

rethumb-error-message: "Height must be less than 513. (#503)"

Error codes

This following list shows all errors that the API may return.

Code Error
#101Datbase error, repeat the request again.
#102Datbase error, repeat the request again.
#103Datbase error, repeat the request again.
#201Storage error, repeat the request again.
#202Storage error, repeat the request again.
#203Storage error, repeat the request again.
#301Version parameter invalid length, value is too long (Max: 16 characters).
#302Version parameter invalid value, value must be alphanumeric: [A-z0-9].
#401Image is too large, try with a smaller image (Max: 512 kB for free accounts).
#402Image MIME type not found, invalid image.
#403Image MIME type not supported, this service doesn't support the found MIME type.
#404Error processing image, generic image error, try again or with a diferent image.
#501Height parameter is not numeric.
#502Height parameter is not a positive number.
#503Height parameter is larger than the max allowed (in free: 512).
#601Width parameter in percent must be numeric.
#602Width parameter in percent must be between 1 and 99.
#603Width parameter is not numeric.
#604Width parameter is not a positive number.
#605Width parameter is larger than the max allowed (in free: 512).
#701Square parameter is not numeric.
#702Square parameter is not a positive number.
#703Square parameter is larger than the max allowed (in free: 512).
#801Width parameter is not numeric.
#802Width parameter is not a positive number.
#803Width parameter is larger than the max allowed (in free: 512).
#804Height parameter is not numeric.
#805Height parameter is not a positive number.
#806Height parameter is larger than the max allowed (in free: 512).
#901EXIF tag not found in image.
#902EXIF invalid tag.
#903EXIF info not found in image.
#904Invalid MIME type for EXIF info.
#1001Error downloading image, try again or use a different URL.
#1101URL not found in parameters.
#1102Parameters duplicated, remove one.
#1103Unknow parameters found in request.
#1201Too many requests, contact info@rethumb.com.
#1202Image is already processed, try again.
#1203Generic error, try again.
#1204Image is being processed, try again.
#1205Image is being processed, try again.