Composition API

Compose a Publication

History

Version	Change
release-2021-06	Initial support for the Composition API in version `beta`
release-2024-03	Added `ignoreComponentConditions` and `componentConditions` query parameters.
release-2025-03	Support in version `2025-03`

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/2025-03/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/2025-03/composition/{documentId}

Parameters

Name	Type	Notes
fields	array<string>	A list of the properties which should be computed and returned. Default: [‘systemdata’, ‘content’, ‘metadata’, ‘includes’, ‘html’, ‘design’]
metadata.preload	object	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}}}`
resolveIncludes	boolean	Resolve 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.renderDirectiveInfo	boolean	Add attributes with the directive name to directive elements.
ignoreComponentConditions	boolean	Added 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`
componentConditions	string	Added 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

{
  "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>"
}

Compose a Publication

With the introduction of the new versioning strategy, the v1 and beta versions are now available as 2025-03 version. If you use any of those versions, you can safely change your integration to the 2025-03 version, which now contains both functionalities without any other changes.

History

Version	Change
release-2021-06	Initial support for the Composition API in version `beta`
release-2024-03	Added `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

Name	Type	Notes
fields	array<string>	A list of the properties which should be computed and returned. Default: [‘systemdata’, ‘content’, ‘metadata’, ‘includes’, ‘html’, ‘design’]
metadata.preload	object	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}}}`
resolveIncludes	boolean	Resolve 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.renderDirectiveInfo	boolean	Add attributes with the directive name to directive elements.
ignoreComponentConditions	boolean	Added 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`
componentConditions	string	Added 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

{
  "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>"
}

Composition API

Compose a Publication 2025-03beta

Description

Advantages

Related

Endpoint

Parameters

Response

Compose a Publication 2025-03beta

Description

Advantages

Related

Endpoint

Parameters

Response

Compose a Publication

Compose a Publication