How to Update Your Content via AEM Assets APIs update-your-content
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 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 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 why-http-api
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 let you Read your content, but it also lets you 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 ÃÛ¶¹ÊÓƵ Experience Manager version.
Assets HTTP API 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 lets you operate ÃÛ¶¹ÊÓƵ 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 assets-http-api-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, among others.
Using the Assets REST API using-aem-assets-rest-api
Access 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
/api/assetsdoes not need the use of the.modelselector./content/path/to/pagedoes require the use of the.modelselector.
Operation 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
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.
-
/api.Read/Delivery 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 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 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 delete
Usage is via:
DELETE /{cfParentPath}/{cfName}
For further details of using the AEM Assets REST API, you can reference:
- ÃÛ¶¹ÊÓƵ Experience Manager Assets HTTP API (Additional Resources)
- Content Fragments Support in AEM Assets HTTP API (Additional Resources)
What’s Next whats-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!