Está viendo la ayuda para la versión:

Learn about Content Fragments Support in AEM Assets HTTP API.

Overview

Nota:

The Assets HTTP API encompasses the:

  • Assets REST API
    • including support for Content Fragments

The current implementation of AEM Assets HTTP API is REST.

The Adobe Experience Manager (AEM) Assets REST API allows developers to access content (stored in AEM) directly over the HTTP API, via CRUD operations (Create, Read, Update, Delete).  

The API allows you to operate AEM 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 very comprehensive, flexible and 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 as they must be hosted in (API) pages that are based on dedicated AEM templates. Not every SPA development organization has access to such resources.  

This is when the Assets REST API can be used. It allows developers to access assets (for example, images and content fragments) directly, without need to first embed them in a page, and deliver their content in serialized JSON format. (Note that it is not possible to customize JSON output from the Assets REST API). 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

The Assets REST API is available on each out-of-the-box install of a recent AEM version.

Nota:

For versions of AEM before 6.5, you have to install a Feature Pack to get full support for content fragments. For some use-cases you then have to perform some additional configuration; see the Security section.

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).

The HTTP method determines the operation to be executed:

  • GET - to retrieve a JSON representation of an asset or a folder
  • POST - to create new assets or folders
  • PUT - to update the properties of an asset or folder
  • DELETE - to delete an asset or folder

Nota:

The request body and/or URL parameters can be used to configure some of these operations; for example, define that a folder or an asset should be created by a POST request.

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

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

Aspect Assets REST API
AEM Component
(components using Sling Models)
Supported use-case(s) General purpose.

Optimized for consumption in a Single Page Application (SPA), or any other (content consuming) context.

Can also contain layout information.

Supported operations

Create, Read, Update, Delete.

With additional operations depending on the entity type.

Read-only.
Access

Can be accessed directly.

Uses the /api/assets endpoint, mapped to /content/dam (in the repository).

For example, to access:
/content/dam/we-retail/en/experiences/arctic-surfing-in-lofoten

request:
/api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.model.json

Needs to be referenced through an AEM component on an AEM page.

Uses the .model selector to create the JSON representation.

An example URL would look like:
http://localhost:4502/content/we-retail/language-masters/en/experience/arctic-surfing-in-lofoten.model.json

Security

Multiple options are possible.

OAuth is proposed; can be configured separately from standard setup.

Uses AEM's standard setup.
Architectural remarks

Write access will typically address an author instance.

Read may also be directed to a publish instance.

As this approach is read-only, it will typically be used for publish instances.
Output JSON-based SIREN output: verbose, but powerful. Allows for navigating within the content. JSON-based proprietary output; configurable through Sling Models. Navigating the content structure is hard to implement (but not necessarily impossible).

Security

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

Nota:

For further information see:

In environments with specific authentication requirements, OAuth is recommended.  

Available Features

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

For further information about features available through the API see:

Paging

The Assets REST API supports paging (for GET requests) via the URL parameters:

  • offset - the number of the first (child) entity to retrieve
  • limit - the maximum number of entities returned

The response will contain 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 (offsetlimit) as specified in the request.

Nota:

Paging is typically applied on container entities (i.e. folders or assets with renditions), as it relates to the children of the requested entity.

Example: Paging

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

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

Entity Types

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, title, etc. Assets are exposed as child entities of folders.

Nota:

Depending on the asset type the list of child entities may already contain the full set of properties that defines the respective child entity. Alternatively, only a reduced set of properties may be exposed for an entity in this list of child entities.

Assets

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

The binary data of an asset is exposed as a SIREN link of type content (also known as the rel attribute).

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

A content fragment is a special type of asset. They can be used to access structured data, such as texts, numbers, dates, amongst others.  

As there are several differences to standard assets (such as images or audio), some additional rules apply to handling them.

Representation

Content fragments:

  • Do not expose any binary data.
  • Are completely contained in the JSON output (within the properties property).
  • Are also considered atomic, i.e. 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

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

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

Associated Content

Associated content is currently not exposed.

Using

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

Precaución:

The dispatcher configuration on AEM cloud instances might block access to /api.

Nota:

For further details, see the API Reference. In particular, Adobe Experience Manager Assets API - Content Fragments.

Read/Delivery

Usage is via:

GET /{cfParentPath}/{cfName}.json

For example:

http://localhost:4502/api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.json

The response is serialized JSON with the content structured as in the content fragment. References are delivered as reference URLs.

Two types of read operations are possible:

  • Reading a specific content fragment by path, this returns the JSON representation of the content fragment.
  • Reading a folder of content fragments by path: this returns the JSON representations of all content fragments within the folder.

Create

Usage is via:

POST /{cfParentPath}/{cfName}

The body has to contain a JSON representation of the content fragment to be created, including any initial content that should be set on the content fragment elements. It is mandatory to set the cq:model property and it must point to a valid content fragment model. Failing to do so will result in an error. It is also necessary to add a header Content-Type which is set to application/json.

Update

Usage is via

PUT /{cfParentPath}/{cfName}

The body has to contain a JSON representation of what is to be updated for the given content fragment.

This can simply be the title or description of a content fragment, or a single element, or all element values and/or metadata. It is also mandatory to provide a valid cq:model property for updates.

Delete

Usage is via:

DELETE /{cfParentPath}/{cfName}

Limitations

There are a few limitations:

  • Variations cannot be written and updated. If those variations are added to a payload (e.g. for updates) they will be ignored. However, the variation will be served via delivery (GET).
  • Content fragment models are currently not supported: they cannot be read or created. To be able to create a new, 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.

Status Codes and Error Messages

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

  1. 202 (OK)

    Returned when:

    • requesting a content fragment via GET
    • successfully updating a content fragment via PUT
  2. 201 (Created)

    Returned when:

    • successfully creating a content fragment via POST
  3. 404 (Not found)

    Returned when:

    • the requested content fragment does not exist
  4. 500 (Internal server error)

    Nota:

    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 via POST)
    • No content fragment model is supplied (null value), resource is null (potentially a permission problem) or the resource is no valid fragment template:
      • No content fragment model specified
      • Cannot create a resource of given model '/foo/bar/qux'
      • Cannot adapt the resource '/foo/bar/qux' to a content fragment template
    • 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 element
      • Could not update fragment data of element

    The detailed error messages are usually returned in the following manner:

    {
      "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

Additional Resources

Esta obra está autorizada con arreglo a la licencia de Reconocimiento-NoComercial-CompartirIgual 3.0 Unported de Creative Commons.  Los términos de Creative Commons no cubren las publicaciones en Twitter™ y Facebook.

Avisos legales   |   Política de privacidad en línea