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 ÃÛ¶¹ÊÓƵ Experience Manager’s (AEM) headless delivery feature.
- Assets REST API
- including support for Content Fragments
The Assets REST API allows developers for ÃÛ¶¹ÊÓƵ 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 ÃÛ¶¹ÊÓƵ 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:
-
follows the
-
implements the
Prerequisites prerequisites
The Assets REST API is available on each out-of-the-box install of a recent ÃÛ¶¹ÊÓƵ Experience Manager as a Cloud Service version.
Key Concepts key-concepts
The Assets REST API offers -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).
- This means that to access the asset at:
/content/dam/path/to/asset
- Request:
/api/assets/path/to/asset
For example, to access /content/dam/wknd/en/adventures/cycling-tuscany, request /api/assets/wknd/en/adventures/cycling-tuscany.json
/api/assetsdoes not need the use of the.modelselector./content/path/to/pagedoes require the use of the.modelselector.
The HTTP method determines the operation to be executed:
- GET - to retrieve a JSON representation of an asset or a folder
- POST - to create assets or folders
- PUT - to update the properties of an asset or folder
- DELETE - to delete an asset or folder
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
(components using Sling Models)
Optimized for consumption in a Single Page Application (SPA), or any other (content consuming) context.
It can also contain layout information.
Create, Read, Update, Delete.
With additional operations, depending on the entity type.
It can be accessed directly.
Uses the /api/assets endpoint, mapped to /content/dam (in the repository).
An example path would look like: /api/assets/wknd/en/adventures/cycling-tuscany.json
It must be referenced through an AEM component on an AEM page.
Uses the .model selector to create the JSON representation.
An example path would look like:/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
Multiple options are possible.
OAuth is proposed; can be configured separately from the standard setup.
Write access typically addresses an Author instance.
Read may also be directed to a Publish instance.
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:
- The Assets REST API
- Entity Types, where the features specific to each supported type (as relevant to Content Fragments) are explained
Paging paging
The Assets REST API supports paging (for GET requests) by way of the URL parameters:
offset- the number of the first (child) entity to retrievelimit- the maximum number of entities returned
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:
-
Do not expose any binary data.
-
Are contained in the JSON output (within the
propertiesproperty). -
They are also considered atomic. That is, the elements and variations are exposed as part of the fragment’s properties vs. as links or child entities. This allows for efficient access to the payload of a fragment.
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.
-
It is recommended that creation is bound to an Author instance (and currently there is no means to replicate a fragment to publish using this API).
-
Delivery is possible from both, as AEM serves requested content in JSON format only.
-
Storage and delivery from an AEM Author instance should suffice for behind-the-firewall, media library applications.
-
For live web delivery, an AEM Publish instance is recommended.
-
/api.Limitations limitations
There are a few limitations:
- Content fragment models are currently not supported: they cannot be read or created. To be able to create or update an existing content fragment, developers have to know the correct path to the content fragment model. Currently the only method to get an overview of these is through the administration UI.
- References are ignored. Currently there are no checks on whether an existing content fragment is referenced. Therefore, for example, deleting a content fragment might result in issues on a page that contains a reference to the deleted Content Fragment.
- JSON data type The REST API output of the JSON data type is string-based output.
Status Codes and Error Messages status-codes-and-error-messages
The following status codes can be seen in the relevant circumstances:
-
200 (OK)
Returned when:
- requesting a content fragment by way of
GET - successfully updating a content fragment by way of
PUT
- requesting a content fragment by way of
-
201 (Created)
Returned when:
- successfully creating a content fragment by way of
POST
- successfully creating a content fragment by way of
-
404 (Not found)
Returned when:
- the requested content fragment does not exist
-
500 (Internal server error)
note note NOTE This error is returned: - when an error that cannot be identified with a specific code has happened
- when the given payload was not valid
The following lists common scenarios when this error status is returned, together with the error message (monospace) generated:
-
Parent folder does not exist (when creating a content fragment by way of
POST) -
No content fragment model is supplied (cq:model is missing), cannot be read (due to an invalid path or a permission problem) or there is no valid fragment model:
No content fragment model specifiedCannot create a resource of given model '/foo/bar/qux'
-
The content fragment could not be created (potentially a permission problem):
Could not create content fragment
-
Title and or description could not be updated:
Could not set value on content fragment
-
Metadata could not be set:
Could not set metadata on content fragment
-
Content element could not be found or could not be updated
Could not update content elementCould not update fragment data of element
The detailed error messages are returned in the following manner:
code language-xml { "class": "core/response", "properties": { "path": "/api/assets/foo/bar/qux", "location": "/api/assets/foo/bar/qux.json", "parentLocation": "/api/assets/foo/bar.json", "status.code": 500, "status.message": "...{error message}.." } }
API Reference api-reference
See here for detailed API references:
-
The Content Fragment and Content Fragment Model OpenAPIs are also available.
Additional Resources additional-resources
For more information, see: