Content structure

An ACE installation normally consists of many different types of content like articles and configuration content, but in many cases also content forming some kind of structure. For an ACE installation powering a website, this could for example be content representing the different pages and sections of the website.

In order to be able to handle this kind of structure, ACE provides the concept of a content structure in the form of the system variant aceStructure, the system aspect aceStructure as well as the Structure service. The service provides an API which can be used to retrieve content structure data - which can then be used for things like navigation - as well as exporting structures packaged in JAR files.

The Structure Service

The Structure Service is deployed within the Content Service and exposes a couple of REST endpoints at the base path /structure.

Content structure retrieval

The endpoint at sub path /alias/${aliasNamespace}/${alias} allows for retrieving a JSON representation of a content structure.

Accepts HTTP GET requests for a single content.

Example:

$ curl -i -s \
    -H "Accept: application/json" \
    -H "X-Auth-Token: $TOKEN" \
    "http://ace-content-service:8081/structure/alias/my/alias"

HTTP/1.1 200 OK
Date: Thu, 12 Sep 2019 07:40:30 GMT
Ace-Response-Origin: ContentService (FQzVRZdxjIXD)
Ace-Api-Version: 1.9.1
Cache-Control: private, no-transform, max-age=60, s-maxage=60
Content-Type: application/json
Content-Length: 262

{
  "id": "contentid/MmRhOWRiOGEtYTc4Mi00",
  "name": "ACE Starter Kit",
  "structureOmitted": false,
  "structure": [
    {
      "id": "contentid/NzU4ZDFkYzAtMWY0YS00",
      "name": "Culture",
      "structureOmitted": false,
      "structure": []
    }
  ]
}

The JSON structure returned is on the following format:

  • id - An ACE alias belonging to the content.
  • name - A name representing the content.
  • structureOmitted - A boolean indicating whether child structure data has been omitted from the response.
  • structure - A list of child structure items on the same format as the top level object.

Structure representation

Each item in the content structure (starting with the root) will be fetched in the system variant aceStructure by the Structure Service. The data returned from the structure variant is expected to include data for the system aspect aceStructure, which contains the following properties:

  • id - string - An ACE alias belonging to the content.
  • name - string - A name representing the content.
  • structure - A list of ACE aliases for any possible child structure entries.

Whether an item has any further child structure is entirely up to the variant implementation.

A composer in the structure variant which returns its child structure from another aspect could for example look like this:

function compose(content) {
  return {
    aspects: {
      aceStructure: {
        id: content.system.id,
        name: content.aspects.section.title,
        structure: content.aspects.section.sections
      }
    }
  };
}

Depth

When the Structure Service returns a structure response for a given content alias, it will automatically also inline the next level of entries since it is very likely that data will be needed. To retrieve the content structure deeper than that, the client will have to make another call to the service using the child alias.

Permissions and authentication

All access to the Structure Service require the caller to be authenticated, i.e. provide a valid ACE authentication token.

The Structure Service response will also automatically be filtered against permissions of the calling user. Any content which the user does not have READ permission for will be omitted from the response.

Caching

The Structure Service will always add a short-time Http Cache-Control header instructing the response to be cacheable for one minute in private caches (which in most cases mean browser caches).

Structure export

The endpoint at sub path /export allows for an entire content structure to be exported as a JAR file, ready to be imported into a target ACE system.

Accepts HTTP POST requests using a JSON object payload containing:

  • rootId - An ACE alias belonging to the that should be used as the root of the export operation.
  • contentTypes - A list of content types. Content with a content type not included in this list will be skipped.

Example

$ curl -i \
    -XPOST
    -H "Content-Type: application/json"
    -H "Accept: application/octet-stream" \
    -H "X-Auth-Token: $TOKEN" \
    -d '{"rootId":"contentid/X", "contentTypes":["contentType1","contentType2"]}'
    "http://ace-content-service:8081/structure/export"

The above example would request an export of the content structure starting at contentid/X and include referenced content of content types contentType1 and contentType2.

Response

HTTP/1.1 200 OK
Date: Mon, 21 Oct 2024 10:57:35 GMT
Ace-Response-Origin: ContentService (RorjivgMggIZ)
Ace-Api-Version: 2.6.1
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="content.jar"
Cache-Control: no-cache, no-store, no-transform, must-revalidate
Content-Length: 732

Warning: Binary output can mess up your terminal. Use "--output -" to tell
Warning: curl to output it to your terminal anyway, or consider "--output
Warning: <FILE>" to save to a file.

How it works

A content structure export works by first building a graph of content found by starting at the content represented by the given rootId alias and recursively visiting all content references in fields of type alias and LIST::alias.

The content graph is then exported into a JAR file on the ACE content import format and returned to the caller as an HTTP octet stream of data.

The following details can be noted:

  • Only content of types given in the contentTypes payload parameter will be included in the export, however the content represented by the given rootId alias payload parameter alias will always be included.
  • Referenced content found to be unavailable (deleted / soft-deleted / not found / not public) will be skipped for the export.

Export permissions

In order to request a content structure export, the calling user has to:

  • Be logged in (authenticated)
  • Be in the sysadmin role in the __global__ context.

Structure export preview

The endpoint at sub path /export/preview allows for a preview of what a structure export would export in the resulting JAR file.

Accepts HTTP POST requests using a JSON object payload containing:

  • rootId - An ACE alias belonging to the content that should be used as the root of the export operation.
  • contentTypes - A list of content types. Content with a content type not included in this list will be skipped.

Example

$ curl -i -s \
    -XPOST
    -H "Content-Type: application/json"
    -H "Accept: application/json" \
    -H "X-Auth-Token: $TOKEN" \
    -d '{"rootId":"contentid/X", "contentTypes":["contentType1","contentType2"]}'
    "http://ace-content-service:8081/structure/export/preview"

The above example would request an export preview of the content structure starting at contentid/X and include referenced content of content types contentType1 and contentType2.

Response

HTTP/1.1 200 OK
Date: Mon, 21 Oct 2024 10:55:42 GMT
Ace-Response-Origin: ContentService (RorjivgMggIZ)
Ace-Api-Version: 2.6.1
Cache-Control: no-cache, no-store, no-transform, must-revalidate
Content-Type: application/json;charset=utf-8
Content-Length: 105

{"id":"contentid/X","contentType":"siteContent","resources":[]}

How it works

A content structure export preview works exactly like the export operation described above, but instead of the response being an HTTP octet stream of a JAR file you will get a JSON representation of the content graph. This can be useful if you want to get an idea of which content would be exported in the actual export operation.

Export preview permissions

In order to request a content structure export preview, the calling user has to:

  • Be logged in (authenticated)
  • Be in the sysadmin role in the __global__ context.