Content Fragments Support in the AEM Assets HTTP API content-fragments-support-in-aem-assets-http-api

Overview overview

Learn about support for Content Fragments in the Assets HTTP API, an important piece of Adobe Experience Manager’s (AEM) headless delivery feature.

The Assets REST API allows developers for Adobe Experience Manager as a Cloud Service to access content (stored in AEM) directly over the HTTP API, by way of CRUD (Create, Read, Update, Delete) operations.

The API lets you operate Adobe Experience Manager as a Cloud Service as a headless CMS (Content Management System) by providing Content Services to a JavaScript front-end application. Or any other application that can execute HTTP requests and handle JSON responses.

For example, Single Page Applications (SPA), framework-based or custom, require content provided over the HTTP API, often in JSON format.

While AEM Core Components provide a customizable API that can serve required Read operations for this purpose, and whose JSON output can be customized, they do require AEM WCM (Web Content Management) know-how for implementation. This is because they must be hosted in pages that are based on dedicated AEM templates. Not every SPA development organization has direct access to such knowledge.

This is when the Assets REST API can be used. It allows developers to access assets (for example, images and content fragments) directly, without the need to first embed them in a page, and deliver their content in serialized JSON format.

The Assets REST API also allows developers to modify content - by creating new, updating, or deleting existing assets, content fragments, and folders.

The Assets REST API:

Prerequisites prerequisites

The Assets REST API is available on each out-of-the-box install of a recent Adobe Experience Manager as a Cloud Service version.

Key Concepts key-concepts

The Assets REST API offers REST-style access to assets stored within an AEM instance.

It uses the /api/assets endpoint and requires the path of the asset to access it (without the leading /content/dam).

For example, to access /content/dam/wknd/en/adventures/cycling-tuscany, request /api/assets/wknd/en/adventures/cycling-tuscany.json

The HTTP method determines the operation to be executed:

The exact format of supported requests is defined in the API Reference documentation.

Transactional Behavior transactional-behavior

All requests are atomic.

This means that subsequent (write) requests cannot be combined into a single transaction that could succeed or fail as a single entity.

AEM (Assets) REST API versus AEM Components aem-assets-rest-api-versus-aem-components

Security security

If the Assets REST API is used within an environment without specific authentication requirements, AEM’s CORS filter must be configured correctly.

In environments with specific authentication requirements, OAuth is recommended.

Available Features available-features

Content Fragments are a specific type of Asset, see Working with Content Fragments.

For more information about features available through the API see:

Paging paging

The Assets REST API supports paging (for GET requests) by way of the URL parameters:

The response contains paging information as part of the properties section of the SIREN output. This srn:paging property contains the total number of (child) entities ( total), the offset, and the limit ( offset, limit) as specified in the request.

Example: Paging example-paging

GET /api/assets.json?offset=2&limit=3

...
"properties": {
    ...
    "srn:paging": {
        "total": 7,
        "offset": 2,
        "limit": 3
    }
    ...
}
...

Entity Types entity-types

Folders folders

Folders act as containers for assets and other folders. They reflect the structure of the AEM content repository.

The Assets REST API exposes access to the properties of a folder. For example, its name, and title. Assets are exposed as child entities of folders and subfolders.

Assets assets

If an asset is requested, the response returns its metadata; such as title, name, and other information as defined by the respective asset schema.

The binary data of an asset is exposed as a SIREN link of type content.

Assets can have multiple renditions. These are typically exposed as child entities, one exception being a thumbnail rendition, which is exposed as a link of type thumbnail ( rel="thumbnail").

Content Fragments content-fragments

A content fragment is a special type of asset. They 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 audio), some additional rules apply to handling them.

Representation representation

Content fragments:

Content Models and Content Fragments content-models-and-content-fragments

Currently the models that define the structure of a content fragment are not exposed through an HTTP API. Therefore, the consumer must know about the model of a fragment (at least a minimum) - although most information can be inferred from the payload; as data types, and so on, are part of the definition.

To create a content fragment, the (internal repository) path of the model has to be provided.

Associated Content associated-content

Associated content is not exposed.

Using using

Usage can differ depending on whether you are using an AEM Author or Publish environment, together with your specific use case.

Limitations limitations

There are a few limitations:

Status Codes and Error Messages status-codes-and-error-messages

The following status codes can be seen in the relevant circumstances:

API Reference api-reference

See here for detailed API references:

Additional Resources additional-resources

For more information, see: