Composition API

Compose a Publication

History
VersionChange
release-2021-06Initial support for the Composition API on /v1/beta
release-2024-03Added ignoreComponentConditions and componentConditions query parameters.

Required scope: public-api:read

Description

The Composition API loads a Publication with all required information to render a whole document with one request.

Advantages
  • Make only one request to get all the required information to render a publication
  • High-performing and efficient preloading of references (e.g. lists, includes, other references)
  • Useful for a pull architecture
  • Deduplication of document teasers: Teasers in li-document-search and li-list-reference are deduplicated across a document, taking into account teasers from li-document-reference and li-document-references as well.
  • The only endpoint which is able to resolve includes
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/beta/composition/:documentId" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @- << EOF
  {
    "fields": ["systemdata", "content", "metadata", "includes", "html"]
  }
  EOF

Endpoint

POST /api/beta/composition/:documentId

Parameters

NameTypeRequiredNotes
fieldsarray<string>A list of the properties which should be computed and returned. Default: [‘systemdata’, ‘content’, ‘metadata’, ‘includes’, ‘html’, ‘design’]
metadata.preloadobject

You can pass metadata properties which should be resolved.
This only works for properties of type li-document-reference, li-document-references, li-list-reference and li-tree.

Example: {"metadata": {"preload": {"myProp": true}}}

resolveIncludesbooleanResolve includes. If true then ‘includes’ will be populated and includes will be resolved in the rendered html. If ‘includes’ is added to the fields array as above, they are resolved in a separate array from the content.
renderOptions.renderDirectiveInfobooleanAdd attributes with the directive name to directive elements.
ignoreComponentConditionsbooleanAdded in: release-2024-03

Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks.

Default: false

componentConditionsstringAdded in: release-2024-03

JSON stringified object which contains the component conditions you would like to apply.

Default: dateTime: new Date()
Example: ?componentConditions={"dateTime":"2024-02-14T17:25:10.391Z"}

Response

200
OK
{
  "systemdata": {
    "projectId": 1,
    "channelId": 1,
    "documentId": 1,
    "contentType": "article",
    "documentType": "article",
    "publicationId": 1,
    "firstPublicationDate": "2022-03-16T14:08:11:000Z",
    "significantPublicationDate": "2022-10-26T07:25:00.000Z",
    "visiblePublicationDate": "2022-10-27T06:00:00.000Z",
    "lastPublicationDate": "2023-03-18T16:32:04.170Z",
    "design": {
      "name": "timeline",
      "version": "1.1.0"
    }
  },
  "content": [
    {
      "id": "doc-1b8i1ksh10",
      "component": "head",
      "identifier": "timeline.head",
      "content": {
        "title": "a title",
        "text": "some lead"
      }
    },
    {
      "id": "doc-2c95a77x14",
      "component": "teaser",
      "identifier": "timeline.teaser",
      "content": {
        "embed-teaser": {
          "service": "embed-teaser",
          "params": {
            "document": {
              "$ref": "document",
              "reference": {
                "id": 7
              }
            }
          }
        }
      }
    }
  ],
  "metadata": {
    "title": "a title",
    "description": "some lead",
    "topic": {
      "$ref": "document",
      "reference": {
        "id": "5"
      },
      "isPreloaded": true,
      "value": {
        "metadata": {
          "title": "Another title"
        },
        "systemdata": {
          "projectId": 1,
          "channelId": 1,
          "documentId": 5,
          "contentType": "article",
          "documentType": "article",
          "publicationId": 7,
          "firstPublicationDate": "2022-03-16T14:08:11:000Z",
          "significantPublicationDate": "2022-10-26T07:25:00.000Z",
          "visiblePublicationDate": "2022-10-27T06:00:00.000Z",
          "lastPublicationDate": "2023-03-18T17:32:04.170Z",
          "design": {
            "name": "timeline",
            "version": "1.1.0"
          }
        }
      }
    }
  },
  "includes": [
    {
      "componentId": "doc-2c95a77x14",
      "directiveName": "embed-teaser",
      "resolvedValue": {
        "content": [
          {
            "id": "ref-7",
            "component": "p",
            "content": {
              "text": "Some text."
            }
          }
        ]
      }
    }
  ],
  "html": "<div>...</div>"
}