Suggest - Fluid Topics - Latest

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

This web service suggests publications and topics based on information entered by end-users.

Method Endpoint
POST 
/api/khub/suggest
  • When a user is authenticated, Fluid Topics retrieves user groups to determine how to filter the content returned in the responses of the search web services.
  • When the HTTP header does not include user credentials, this web service only returns public results.
  • This web service suggests only the titles of book topics. It does not suggest the titles of article topics.

As a USER_ADMIN user, it is possible to impersonate another user when using this web service.

This web service requires authentication on portals with mandatory authentication.

Request example

{
  "input": "exampleInput",
  "contentLocale": "en-US",
  "metadataFilters": [
    {
      "key": "filterKey1",
      "valueFilter": {
        "values": [
          "value1",
          "value2"
        ],
        "negative": false
      }
    },
    {
      "key": "filterKey2",
      "dateFilter": {
        "type": "LAST_MONTH"
      }
    },
    {
      "key": "filterKey3",
      "rangeFilter": {
        "from": "2022-01-01",
        "to": "2022-12-31"
      }
    }
  ],
  "sort": [
    {
      "key": "sortKey1",
      "order": "ASC",
      "type": "ALPHA"
    }
  ],
  "maxCount": 5
}
Field Type Required? Description
input String Yes Expects the string query used to return suggestions.
contentLocale String No Expects the content language's ISO code.
metadataFilters Array No Filters the results based on selected criteria including metadata and date ranges. Defaults to an empty list.
key String No Expects a metadata key.
valueFilter Object No Contains the filtering conditions based on metadata values.
values Array No Defines the value for the selected key. When multiple values are defined, they are combined with an AND or an OR operator depending on the tenant's configuration.
negative Boolean No When true, this parameter excludes results matching the previously defined values. By default, the negative parameter is implicit and false.
dateFilter Object No Specifies the date-based filtering conditions using predefined periods.
type String No Restricts results to those within a predefined period. Acceptable values are LAST_WEEK, LAST_MONTH, LAST_QUARTER, LAST_YEAR.
rangeFilter Object No Specifies custom date range filtering.
from String No The inclusive start date of the period. If unspecified, the default value is 1970-01-01.
to String No The inclusive end date of the period. If unspecified, the default value is the current day.
sort Array No Enables specifying a custom sort on any metadata.
key String No Sort criterion based on metadata key.
order String No Sort order can be ascending (ASC) or descending (DESC).
type String No Type of sorting, such as ALPHA for alphabetical sorting. Defaults to the standard sorting order.
maxCount Number No Declares the maximum number of returned suggestions. Limited to 1000 replies at most on the server-side. Defaults to 5.

It is not possible use multiple filters for one key in metadataFilters. One key goes with either valueFilter, dateFilter, or rangeFilter.

Response body

{
  "suggestions": [
    {
      "type": "MAP",
      "editorialType": "BOOK",
      "value": "This is a Book suggestion"
    },
    {
      "type": "MAP",
      "editorialType": "ARTICLE",
      "value": "This is an Article suggestion"
    },
    {
      "type": "TOPIC",
      "value": "This is a book Topic suggestion"
    },
    {
      "type": "DOCUMENT",
      "value": "This is a Unstructured Document suggestion",
      "filenameExtension": "docx",
      "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    }
  ]
}
Field Type Description
value String The string displayed in the suggestion box.
type String Indicates the type of object the suggestion comes from:
  • MAP: a structured publication title.
  • TOPICS: a book topic title.
  • DOCUMENT: an unstructured document title.
editorialType String Indicates, for MAP types only, if the suggested structured publication is a BOOK or an ARTICLE.
mimetype String Indicates, for DOCUMENT types only, the MIME type of the suggestion.
filenameExtension String Indicates, for DOCUMENT types only, the filename extension of the suggestion.