The REST Media API provides access to all kinds of media assets in the Product Manager.

Single Media Asset File

URL Pattern	`/media/{quality/derivativeDefinition}/{identifier}`
Method	GET
Parameters	`lastModified`	DATETIME
Content types	application/octet-stream
Returns	the media asset file as binary data stream

Preview of Media Asset File

URL Pattern	`/media/{identifier}/preview`
Method	GET
Parameters	`size`	All allowed values: small \| medium \| large
Content types	image/jpg
Returns	the media asset preview as binary jpeg

Media Asset File Location

URL Pattern	`/media/{quality/derivativeDefinition}/{identifier}`
Method	GET
Parameters	-
Content types	text/plain
Returns	the URL to the media asset file

Upload single Media Asset File

To upload a local image to the media asset server, the following two steps should be performed:

call the REST File API to upload a local file to the PIM storage, which returns a result contains id for the uploaded file.
call the following REST API to add the uploaded file to the media manager. The path parameter "fileId" is the id of the returned file object of the first step.

URL Pattern	`/media/{fileId}`
Method	POST
Parameters	`categoryId`	optional parameter indicates the id of the category
Content types	text/plain
Returns	the identifier of the uploaded media asset file

The query parameter "categoryId" is optional, it indicates the id of the category to which the added media asset file should belong. If it is not given, the media asset file will be assigned to the default category.

Examples

Retrieve single media asset file in 36dpi JPEG quality with identifier D123456

Rest Call

curl -u rest:heiler -H "Accept: application/octet-stream" -X GET http://localhost:1501/rest/V1.0/media/JPEG 36dpi/D123456

Rest Client Java Code

MediaRequest mediaAssetRequest = restClient.createMediaRequest();
    
InputStream result = mediaAssetRequest.getMediaAsset( "D123456", "JPEG 36dpi", null );

Return media asset file only if modified after given time (otherwise empty stream is returned):

Rest Call

curl -u rest:heiler -H "Accept:application/octet-stream" -X GET http://localhost:1501/rest/V1.0/media/JPEG 36dpi/D123456?lastModified=2012-09-26T15:33:12

Rest Client Java Code

MediaRequest mediaRequest = restClient.createMediaRequest();
 
Timestamp lastModified = new Timestamp( calendar.getTime().getTime() );
 
InputStream result = mediaRequest.getMediaAsset( "D123456", "JPEG 36dpi", lastModified );

Retrieve media asset file preview

Rest Call

curl -u rest:heiler -H "Accept: image/jpg" -X GET http://localhost:1501/rest/V1.0/media/D123456/preview?size=small 

Rest Client Java Code

MediaRequest mediaRequest = restClient.createMediaRequest();
 
PreviewSize size = PreviewSize.BIG;
 
InputStream result = mediaAssetRequest.getMediaAssetPreview( "D123456", size );

Retrieve media asset file location

curl -u rest:heiler -H "Accept: text/plain" -X GET http://localhost:1501/rest/V1.0/media/JPEG 36dpi/D123456

Rest Client Java Code

MediaRequest mediaRequest = restClient.createMediaRequest();
 
URL mediaAssetUrl = mediaRequest.getMediaAssetLocation( "D123456", "JPEG 36dpi");

Upload media asset file to media asset server

call REST File API to upload a local file to the PIM storage

curl -u rest:heiler -H "Accept: application/json" -H "Content-Type:application/octet-stream"  --data-binary "@Test.jpg" -X POST http://localhost:1501/rest/V1.0/manage/file?originalFilename=Test.jpg

Rest Client Java Code

FileUploadRequest fileUploadRequest = restClient.createFileUploadRequest();
 
FileReference result = fileUploadRequest.uploadFile( "Test.jpg", inputStream );

An object including an ID and an URL is returned:

{
  "id": "feb3cd45-d27e-4700-912e-26014512a6e3",
  "originalFilename": "Test.jpg"
}

Then call following Rest Media API to add the uploaded file to the media asset server(in the default category) .

Rest Call

curl -u rest:heiler -H "Accept: text/plain" -X POST http://localhost:1501/rest/V1.0/media/feb3cd45-d27e-4700-912e-26014512a6e3

Rest Client Java Code

MediaRequest mediaRequest = restClient.createMediaRequest();
 
String mediaAssetIdentifier = mediaRequest.addMediaAsset( "feb3cd45-d27e-4700-912e-26014512a6e3");

Or call the same API with query parameter "categoryId" to add the uploaded file in desired category

curl -u rest:heiler -H "Accept: text/plain" -X POST http://localhost:1501/rest/V1.0/media/feb3cd45-d27e-4700-912e-26014512a6e3?categoryId=009900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

Rest Client Java Code

MediaRequest mediaRequest = restClient.createMediaRequest();
 
String mediaAssetIdentifier = mediaRequest.addMediaAsset( "feb3cd45-d27e-4700-912e-26014512a6e3", "009900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000");