Adobe Experience Manager Assets HTTP API

Overview

The Assets HTTP API allows for create-read-update-delete (CRUD) operations on digital assets, including on metadata, on renditions, and on comments, together with structured content using Experience Manager Content Fragments. It is exposed at /api/assets and is implemented as REST API. It includes support for Content Fragments.

To access the API:

1. Open the API service document at https://[hostname]:[port]/api.json.
2. Follow the Assets service link leading to https://[hostname]:[server]/api/assets.json.

The API response is a JSON file for some MIME types and a response code for all MIME types. The JSON response is optional and may not be available, for example for PDF files. Rely on the response code for further analysis or actions.

Content Fragments

A Content Fragment is a special type of asset. It can be used to access structured data, such as texts, numbers, dates, among others. As there are several differences to standard assets (such as images or documents), some additional rules apply to handling Content Fragments.

For more information, see Content Fragments support in the Experience Manager Assets HTTP API.

Data model

The Assets HTTP API exposes two major elements, folders and assets (for standard assets). Also, it exposes more detailed elements for the custom data models that describe structured content in Content Fragments. See Content Fragment data models for further information.

Folders

Folders are like directories as in the traditional file systems. Folder can contain just assets, just folders, or folders and assets. Folders have the following components:

Entities: The entities of a folder are its child elements, which can be folders and assets.

Properties:

• name is the name of the folder. This is the same as the last segment in the URL path without the extension.
• title is an optional title of the folder which can be displayed instead of its name.

Links Folders expose three links:

• self: Link to itself.
• parent: Link to the parent folder.
• thumbnail: (Optional) link to a folder thumbnail image.

Assets

In Experience Manager an asset contains the following elements:

• The properties and metadata of the asset.
• Originally uploaded binary file of the asset.
• Multiple renditions as configured. These can be images of different sizes, videos of different encodings, or extracted pages from PDF or Adobe InDesign files.
• Optional comments.

For information about elements in Content Fragments see Content Fragments Support in Experience Manager Assets HTTP API.

In Experience Manager a folder has the following components:

• Entities: The children of assets are its renditions.
• Properties.
• Links.

Available features

The Assets HTTP API includes the following features:

• Retrieve a folder listing.
• Create a folder.
• Create an asset (deprecated)
• Update asset binary (deprecated).
• Update asset metadata.
• Create an asset rendition.
• Update an asset rendition.
• Create an asset comment.
• Copy a folder or asset.
• Move a folder or asset.
• Delete a folder, asset, or rendition.

Retrieve a folder listing

Retrieves a Siren representation of an existing folder and of its child entities (subfolders or assets).

Request: GET /api/assets/myFolder.json

Response codes: The response codes are:

• 200 - OK - success.
• 404 - NOT FOUND - folder does not exist or is not accessible.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Response: The class of the entity returned is an asset or a folder. The properties of contained entities are a subset of the full set of properties of each entity. To obtain a full representation of the entity, clients should retrieve the contents of the URL pointed to by the link with a rel of self.

Create a folder

Creates a sling: OrderedFolder at the given path. If * is provided instead of a node name, the servlet uses the parameter name as node name. The request accepts either of the following:

• A Siren representation of the new folder
• A set of name-value pairs, encoded as application/www-form-urlencoded or multipart/ form- data. These are useful to create a folder directly from an HTML form.

Also, properties of the folder can be specified as URL query parameters.

An API call fails with a 500 response code if the parent node of the provided path does not exist. A call returns a response code 409 if the folder exists.

Parameters: name is the folder name.

Request

• POST /api/assets/myFolder -H"Content-Type: application/json" -d '{"class":"assetFolder","properties":{"title":"My Folder"}}'
• POST /api/assets/* -F"name=myfolder" -F"title=My Folder"

Response codes: The response codes are:

• 201 - CREATED - on successful creation.
• 409 - CONFLICT - if folder exists.
• 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Create an asset

See asset upload for information on how to create an asset. You cannot create an asset using the HTTP API.

Update an asset binary

See asset upload for information on how to update asset binaries. You cannot update an asset binary using the HTTP API.

Update metadata of an asset

Updates the Asset metadata properties. If you update any property in the dc: namespace, the API updates the same property in the jcr namespace. The API does not sync the properties under the two namespaces.

Request: PUT /api/assets/myfolder/myAsset.png -H"Content-Type: application/json" -d '{"class":"asset", "properties":{"dc:title":"My Asset"}}'

Response codes: The response codes are:

• 200 - OK - if Asset has been updated successfully.
• 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
• 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Create an asset rendition

Create a rendition for an asset. If request parameter name is not provided, the file name is used as rendition name.

Parameters: The parameters are name for name of the rendition and file as a file reference.

Request

• POST /api/assets/myfolder/myasset.png/renditions/web-rendition -H"Content-Type: image/png" --data-binary "@myRendition.png"
• POST /api/assets/myfolder/myasset.png/renditions/* -F"name=web-rendition" -F"file=@myRendition.png"

Response codes

• 201 - CREATED - if Rendition has been created successfully.
• 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
• 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Update an asset rendition

Updates respectively replace an asset rendition with the new binary data.

Request: PUT /api/assets/myfolder/myasset.png/renditions/myRendition.png -H"Content-Type: image/png" --data-binary @myRendition.png

Response codes: The response codes are:

• 200 - OK - if Rendition has been updated successfully.
• 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
• 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Add a comment on an asset

Parameters: The parameters are message for the message body of the comment and annotationData for the Annotation data in JSON format.

Request: POST /api/assets/myfolder/myasset.png/comments/* -F"message=Hello World." -F"annotationData={}"

Response codes: The response codes are:

• 201 - CREATED - if Comment has been created successfully.
• 404 - NOT FOUND - if Asset could not be found or accessed at the provided URI.
• 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Copy a folder or an asset

Copies a folder or asset available at the provided path to a new destination.

Request Headers: The parameters are:

• X-Destination - a new destination URI within the API solution scope to copy the resource to.
• X-Depth - either infinity or 0. Using 0 only copies the resource and its properties and not its children.
• X-Overwrite - Use F to prevent overwriting an asset at the existing destination.

Request: COPY /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-copy"

Response codes: The response codes are:

• 201 - CREATED - if folder/asset has been copied to a non-existing destination.
• 204 - NO CONTENT - if the folder/asset has been copied to an existing destination.
• 412 - PRECONDITION FAILED - if a request header is missing.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Move a folder or an asset

Moves a folder or asset at the given path to a new destination.

Request Headers: The parameters are:

• X-Destination - a new destination URI within the API solution scope to copy the resource to.
• X-Depth - either infinity or 0. Using 0 only copies the resource and its properties and not its children.
• X-Overwrite - Use either T to forcibly delete an existing resources or F to prevent overwriting an existing resource.

Request: MOVE /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-moved"

Response codes: The response codes are:

• 201 - CREATED - if folder/asset has been copied to a non-existing destination.
• 204 - NO CONTENT - if the folder/asset has been copied to an existing destination.
• 412 - PRECONDITION FAILED - if a request header is missing.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Delete a folder, an asset, or a rendition

Deletes a resource (-tree) at the provided path.

Request

• DELETE /api/assets/myFolder
• DELETE /api/assets/myFolder/myAsset.png
• DELETE /api/assets/myFolder/myAsset.png/renditions/original

Response codes: The response codes are:

• 200 - OK - if folder has been deleted successfully.
• 412 - PRECONDITION FAILED - if root collection cannot be found or accessed.
• 500 - INTERNAL SERVER ERROR - if something else goes wrong.

Tips, best practices, and limitations

• After the Off Time, an asset and its renditions are not available via the Assets web interface and through the HTTP API. The API returns 404 error message if the On Time is in the future or Off Time is in the past.

• Assets HTTP API does not return the complete metadata. The namespaces are hardcoded and only those namespaces are returned. For complete metadata, see the asset path /jcr_content/metadata.json.

• Some properties of folder or asset are mapped to a different prefix when updated using APIs. The jcr prefix of jcr:title, jcr:description, and jcr:language are replaced with dc prefix. Hence in the returned JSON, dc:title and dc:description contain the values of jcr:title and jcr:description, respectively.

See also

• Translate Assets
• Assets supported file formats
• Search assets
• Connected assets
• Asset reports
• Metadata schemas
• Download assets
• Manage metadata
• Search facets
• Manage collections
• Bulk metadata import

Business.Adobe.com resources