Webservice API

All calls to the new API are made by specifying an operation along with it’s arguments in the URL, for example: /thumbnail/78x100/. Operations should generally be specified in the order they should be performed. Some operations however, such as setting quality or format, can be placed anywhere.

The base URL is now http://<dims_host>/dims3/.

Example remote URL:

http://<dims-host>/dims3/12AB/resize/100x100/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Using mod_dims you can also directly manipulate images on the local filesystem. The API call is still the same but instead of referencing the remote image at the end of the URL you specify the local image at the beginning.

Here is how the same call above would look if mod_dims was installed on an origin server:

http://<dims-host>/archive/2009/03/17/DSC_D300_1872.web.jpg/12AB/resize/100x100/

The image to the right was used as the sample image for the following examples. Click on the image to see it full size.

Crop an Image

Region can be specified as widthxheight{+-}x{+-}y{%}

Example

Crop an image to 100×100 offset 10 pixels from the top left corner.

http://dims-host/dims3/12AB/crop/100x100+10+10/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Generate a Thumbnail

Thumbnail size can be specified as widthxheight{%} {@} {!} {<} {>}.

By default, the width and height are maximum values. That is, the image is expanded or contracted to fit the width and height value while maintaining the aspect ratio of the image. Append an exclamation point to the geometry to force the image size to exactly the size you specify. For example, if you specify 640×480! the image width is set to 640 pixels and height to 480.

If only the width is specified, the width assumes the value and the height is chosen to maintain the aspect ratio of the image. Similarly, if only the height is specified (e.g., /thumbnail/x256/, the width is chosen to maintain the aspect ratio.)

To specify a percentage width or height instead, append . The image size is multiplied by the width and height percentages to obtain the final image dimensions. To increase the size of an image, use a value greater than 100 (e.g. 125). To decrease an image’s size, use a percentage less than 100. Be sure to properly encode the % value as %25, for example 50%25

Use @ to specify the maximum area in pixels of an image.

Use ^ to set a minimum image size limit. The geometry 640×480^, for example, means the image width will not be less than 640 and the image height will not be less than 480 pixels after the resize. One of those dimensions will match the requested size, but the image will likely overflow the space requested to preserve its aspect ratio.

Example

Generate a 78×110 thumbnail of an image, maintaining the original aspect ratio but cropping down to size.

http://dims-host/dims3/12AB/thumbnail/78x110/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Resize an Image

New image size can be specified as widthxheight{%} {@} {!} {<} {>} {^}.

See thumbnail information for more details on geometry parameters.

Example

Resize an image down to 200×200 maintaining the aspect ratio.

http://dims-host/dims3/12AB/resize/200x200/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Reformat an Image

Valid formats are ’’png’’, ’’jpg’’ and ’’gif’’.

Example

Reformat a JPG image to a PNG.

http://dims-host/dims3/12AB/format/png/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Reduce the quality of an Image

Valid quality range is 0 to 100. This has the main affect of reducing the size of the final image.

Example

Reduce quality to 25.

http://dims-host/dims3/12AB/quality/25/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Combine operations in a single call

Example

Reformat JPG to PNG, generate a thumbnail at 78×110 and reduce the quality to 50.

http://dims-host/dims3/12AB/thumbnail/78x110/format/png/quality/50/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg