API: Calls

Doc Instance Resource

Resource URI

			/doc/{id} (searching and getting information about the file)
                        /file/{id_hash} (requesting renditions or the original file synchronously)
		

Resource Properties

A Doc instance resource is represented by the following properties:

Property Description
id A 10 digit number that uniquely identifies this resource.
id_hash A string of 10 letters and numbers that uniquely identifies this resource.
client_id A 10 digit number that uniquely identifies the owning client
name The original name of the file
type The mimetype
meta Key-value paris of meta-data
available_types An array of types this document can be converted to
visibility Public or Private - each client has a default. All renditions are public.

Methods

HTTP GET

Returns the single Doc resource identified by {id}. GET is also used to request a new rendition using resize or crop. Crop & resize may be done in the same request, but for now crop will be applied first.

Basic GET

A document may be converted to other types that are listed in available_types

Property Description
id Int: The ID of the doc to get
key String: The key for the client who owns this file
format String (json|html): Data will be returned in this format
meta Int: Flag - return meta data or not (default)
Examples

Fetch information in json format
/doc/{id}/?key={client_key}&format=json&key={client_key}

Fetch HTML about an asset, with meta data
/doc/{id}/?key={client_key}&format=html&meta=1&key={client_key}

Type Conversion

A document may be converted to other types that are listed in available_types

Property Description
request String: Request this document in a new format (or rendition)
Examples - assuming the original was a .doc

Request and return the original doc
/file/{id_hash}

Request and return a PDF of the .doc
/file/{id_hash}/?request=pdf

Request and return a PNG of the .doc
/file/{id_hash}/?request=png

Request and return a 300 pixel wide and 400 px tall JPG of the .doc
/file/{id_hash}/?request=jpg&resize=width:300|height:400

Resize

Percent may not be combined with width or height. If only a width or height are provided, the image will be constrained in one direction and the aspect ratio will be preserved.

Property Description
resize width and height or percentage, ex: resize=width:200 resize=width:300|height:400 resize=percent:50

Crop

Property Description
crop top and left are required (width and height) or (bottom and right) are required. ex: crop=top:50|left:100|width:300|height:400
example of resize and crop mixed resize=width:300,crop=top:50|left:100|width:300|height:400 - crop will be applied before resizing

Grayscale

Produce a grayscale version of an image. This may be combined with crop or resize

Property Description
resize Flag indicating the image should be converted to grayscale. Value: 1
Examples

Convert to grayscale
/file/{id_hash}/?grayscale=1

Search assets that belong to your client

Property Description
key Client key
format html or json
Examples

Search assets - json results
/doc/search/&key={client_key}&format=json

Search assets - HTML resutls, with metadata and maps
/doc/search/&key={client_key}&format=html&meta=1&maps=1

HTTP POST

Creates a single Doc resource

Property Description
name String: original file name
contents The contents of the file
download_url The url of the file to download (use instead of posting content & name)
callback After the requested action is complete, the object will be posted to this URL - optional
metadata An optional object of json encoded meta data to attch to this asset
ttl Seconds from now until the imate is removed from the system (optional)
visibility Public or Private - each client has a default. All renditions are public.

Note: You can also send a posted file in the traditional way a form with enctype="multipart/form-data" submits a file. Name that file "file". When you do this you don't need to send name or contents across.

PHP Example
		// setup some vars and an array of params for CURL
		$file = "/path/to/your/file.jpg";
		$contents = file_get_contents($file);
		$key = 'a3d9f221';
		$params = array(
    			'name' => $name,
    			'download_url' => 'http://example.com/file.jpg',
    			'format' => 'json',
    			'key' => $key,
    			'ttl' => 300, // optional
    			'visibility' => 'Public', // optional
    			'contents' => $contents,
    			'metadata' => '{"foo":"bar","album":"Test"}',
		);

		// POST some data
		$ch = curl_init('http://media.deseretdigital.com/doc');
		$options = array(
    			CURLOPT_POST => true,
    			CURLOPT_RETURNTRANSFER => true,
    			CURLOPT_POSTFIELDS => $params,
		);
		curl_setopt_array($ch, $options);

		$results = curl_exec($ch);
		// the response should be json, since that was in the params array
		$response = json_decode($results);
		print_r($response);
		

HTTP PUT

Updates a single Doc resource identified by {id}. Identical to POST, except PUT accepts an {id}

HTTP DELETE

Not supported