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.

The Structure Service

The Structure Service is deployed within the Content Service and expose a single REST endpoint at the path /structure. The endpoint accept Http GET requests for a single content, and will deliver content structure JSON representing the structure.

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