Update/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 modifies the metadata of the publication defined in the endpoint by either updating or replacing the metadata 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.
  • Using the replace mode deletes all of the metadata previously assigned to a publication or its topics in the case of a structured document.
  • 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.
  • 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.
  • It is not necessary to reprocess content for the metadata update to take effect.
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 be updated.

Targeting publications by using the same metadata key with two different values (audience=internal&audience=external) relies on the Behavior parameters of the Search page facets menu:

  • If the Value selection and combination of the audience metadata key is Multiple — Or, all publications with internal or external receive the metadata update.
  • If the Value selection and combination of the audience metadata key is Multiple — And, all publications with internal and external receive the metadata 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.

Updating metadata deletes the previous value and replaces it with the newly defined value.

Request example

The following lines show an example of JSON request body:

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

The request body expects the following fields:

Field Type Required? Description
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 The new value(s) to associate with the metadata key.
mode String Yes The mode parameter has two possible values:
  • update (default): keeps the publication's previous metadata and replaces the specified key / value pairs the with the newly defined metadata.
  • replace: deletes the publication's previous metadata and replaces it only with the newly defined metadata.
inheritance Boolean Yes The inheritance parameter has two possible values:
  • true: the document's topics inherit the new metadata.
  • false: the document's topics do not inherit the new metadata.
The default value is true.

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.

If a user wants to update a metadata with multiple values, the request field must be values instead of value.

Return code Description
202 ACCEPTED The update instruction was sent to the Fluid Topics processing pipeline.
400 BAD REQUEST Invalid query.
500 INTERNAL SERVER ERROR The server could not process the request.

Update versus replace

When defining the update value for the mode parameter, the publication's previous metadata is visible along with the newly defined metadata as follows:

Update mode

When defining the replace value for the mode parameter, all of the publication's previous metadata is deleted and replaced by only the newly defined metadata as follows:

Replace mode