Add, update, or replace publication metadata - Fluid Topics - Latest

Fluid Topics API Reference Guide
Category
Reference Guides
Audience
public
Version
Latest

As documentation evolves, it may be necessary to modify the metadata associated with it. This web service adds to, updates, or replaces metadata for the publication defined in the endpoint, using the values specified in the request body.

  • Users or API keys with the CONTENT_PUBLISHER role can only update the metadata of a publication published through a source they have permissions for.
  • Reuploading a publication with its original metadata overrides changes made using this web service. Whenever possible, update the source content instead of using this web service.
  • It is not necessary to reprocess content for the metadata update to take effect.
  • It is necessary to provide an Ft-Calling-App value when using Fluid Topics web services. See Fluid Topics calling app.
  • It is possible to update or replace all custom metadata with this web service.
  • It is possible to update or replace the following built-in metadata with this web service: ft:title, ft:locale, ft:openMode, ft:originUrl, ft:clusterId, ft:lastEdition, ft:editorialType, and ft:description.
Method Endpoint
PUT 
/api/admin/khub/publications/update-metadata?metadata1=value1&...&metadataN=valueN
Query string parameter Type Required? Description
metadata=value String Yes Any metadata key-value set that is unique to the publication to update.
The document's originId is often a good candidate for use in the endpoint as it is the publication's unique identifier.
The metadata targeted in the endpoint is only used to identify the publication to be updated and is not itself updated.

Targeting publications by using the same metadata key with two different values (category=training&category=guides) relies on the configuration of the Metadata menu. If the Filter selection mode value of the category metadata key is:

  • Match any filter: all publications with either category=training, or category=guides, receive the metadata update.
  • Match all filters: only publications with both category=training and category=guides receive the metadata update.

Request example

The following example shows a JSON request body for this web service:

{
  "mode": "update",
  "metadata": [
    {
      "key": "product",
      "value": "Fluid Topics"
    },
    {
      "key": "audience",
      "values": [
        "public",
        "internal"
      ]
    },
    {
      "key": "versions",
      "hierarchicalValues": [
        [
          "3.x.x",
          "3.6.x",
          "3.6.2"
        ],
        [
          "3.x.x",
          "3.6.x",
          "3.6.3"
        ]
      ]
    }
  ],
  "inheritance": false
}

The request body expects the following fields:

Field Type Required? Description
mode String No The default value of mode is update. If the value of mode is update:
  • Fluid Topics keeps the publication's existing custom metadata. Fluid Topics adds the keys provided in the request body (if new), or updates them (if they already exist). Keys not mentioned in the request are left unchanged.
If the value of mode is replace:
  • Fluid Topics deletes the publication's existing custom metadata. Fluid Topics replaces the existing custom metadata with the metadata provided in the request body. Any existing key not included in the request body is removed.
    Use replace mode with great caution.
By default, a document's topics inherit the updated metadata. It is possible to override this behavior by setting the value of the inheritance parameter to false in the JSON request body.
metadata Array Yes Expects the list of the new metadata key-value sets.
key String Yes The metadata key associated with the values to be updated.
value String Yes Defines a single value for the selected key.
To update a metadata key with multiple values, the request field must be values instead of value.
values String Yes Defines values for the selected key.
hierarchicalValues Array Yes Defines hierarchical values for the selected key. It can have an unlimited number of arrays, each representing a hierarchical metadata key. Inside an array, the first string is the value highest in the hierarchy. Each following value is one level down.
inheritance Boolean No true by default. If true, the document's topics inherit the updated metadata. If false, the document's topics do not inherit the new metadata.
If mode is set to replace and inheritance is set to true, metadata are replaced at the document level but updated at the topic level.
Return code Description
202 ACCEPTED The update instruction was sent to the Fluid Topics processing pipeline.
400 BAD REQUEST Invalid query.