How to Update Your Content via AEM Assets APIs

In this part of the AEM Headless Developer Journey, learn how to use the REST API to access and update the content of your Content Fragments.

The Story So Far

In the previous document of the AEM headless journey, How to Access Your Content via AEM Delivery APIs you learned how to access your headless content in AEM via the AEM GraphQL API and you should now:

  • Have a high-level understanding of GraphQL.
  • Understand how the AEM GraphQL API works.
  • Understand some practical sample queries.

This article builds on those fundamentals so you understand how to update your existing headless content in AEM via the REST API.

Objective

  • Audience: Advanced
  • Objective: Learn how to use the REST API to access and update the content of your Content Fragments:
    • Introduce the AEM Assets HTTP API.
    • Introduce and discuss Content Fragment support in the API.
    • Illustrate details of the API.

Why do You Need the Assets HTTP API for Content Fragment

In the previous stage of the Headless Journey, you learned about using the AEM GraphQL API to retrieve your content using queries.

So why is another API needed?

The Assets HTTP API does allow you to Read your content, but it also allows you to Create, Update and Delete content - actions that are not possible with the GraphQL API.

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

Assets HTTP API

The Assets HTTP API encompasses the:

  • Assets REST API
  • including support for Content Fragments

The current implementation of the Assets HTTP API is based on the REST architectural style and enables you to access content (stored in AEM) via CRUD operations (Create, Read, Update, Delete).

With these operation the API allows you to operate Adobe Experience Manager 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 an API, often in JSON format.

Assets HTTP API and Content Fragments

Content Fragments are used for headless delivery, and a Content Fragment is a special type of asset. They are used to access structured data, such as texts, numbers, dates, amongst others.

Using the Assets REST API

Access

The Assets REST API 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
  • You need to 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

NOTE

Access over:

  • /api/assets does not need the use of the .model selector.
  • /content/path/to/page does require the use of the .model selector.

Operation

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
NOTE

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.

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

  • It is strongly 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.

CAUTION

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

NOTE

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://<host>/api/assets/wknd/en/adventures/cycling-tuscany.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.

Delete

Usage is via:

DELETE /{cfParentPath}/{cfName}

For further details of using the AEM Assets REST API, you can reference:

  • Adobe Experience Manager Assets HTTP API (Additional Resources)
  • Content Fragments Support in AEM Assets HTTP API (Additional Resources)

What’s Next

Now that you have completed this part of the AEM Headless Developer Journey, you should:

  • Understand the basics of the AEM Assets HTTP API.
  • Understand how Content Fragments are supported in this API.

You should continue your AEM headless journey by next reviewing the document How to Go Live with Your Headless Application where you actually take your AEM Headless project live!

Additional Resources

On this page