Search topics - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

This web service searches a topic's title, content, and metadata. It returns topics matching the query conditions through a paginated response body.

The spellcheck option is activated by default. If the query is misspelled, the request is launched again with the new spelling suggested by the spellchecker.

Facets can be added for users to filter the matching publications.

Method Endpoint
POST /api/khub/topics/search
Query string parameter Type Required? Description
page Number No Expects the page number. Starts at 1 and defaults to 1.
per_page Number No Expects the number of results per page. Defaults at -1, meaning that all results are returned. The maximum accepted value is 500.
from String No The inclusive start date of the period on which to filter results based on the value of a topic's ft:lastTechChange metadata. If unspecified, the default value is 1970-01-01.
to String No The inclusive end date of the period. The inclusive start date of the period. If unspecified, the default value is the current day.
  • It is possible to use pagination with this web service.
  • Using pagination when searching topics is recommended.
  • It is possible to specify a period for this web service using either query parameters or fields in the request body. If both methods are used, the values of the query parameters take precedence.

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

Return code Description
200 OK Returns 0 or more results.
400 BAD REQUEST Invalid JSON request body.
500 INTERNAL SERVER ERROR The server could not process the request.
404 NOT FOUND No topic matching the filters configured in the path parameters was found.

Request body

The following lines show an example of a JSON request body:

The word "metadata" is deliberately misspelled as "metadatq" as the value for the query field.

{
  "query": "metadatq",
  "contentLocale": "en-US",
  "filters": [
    {
      "key": "version",
      "values": ["1.1", "1.2"]
    },
    {
      "key": "category",
      "values": ["Reference Guides"]
    }
  ],
  "sort": [
    {
      "key": "ft:lastPublication",
      "order": "DESC"
    }
  ],
  "facets": [
    {
      "id": "author",
      "maxDepth": 1
    }
  ],
  "lastModified": {
    "from": "2024-01-01",
    "to": "2024-04-09"
  },
  "paging": {
    "page": 1,
    "perPage": 20
  }
}

The JSON request body expects the following fields:

Field Type Required? Description
query String No Expects the string query used to return matching publications. If not set, the results are based on other parameters, such as contentLocale and filters.
contentLocale String Yes Expects the content language ISO codes (language and country). If not set, the query fails. If set with an unknown value, Fluid Topics attempts to correct the value. For example, fr is replaced by fr-FR.
uiLocale String No Expects the UI language ISO code. If not set, Fluid Topics tries to detect the user locale. This locale is used to return facet labels in the correct language, for instance.
filters Array No Filters the results on some metadata values.

The filter object expects the following criteria:
  • key (mandatory): Filter keys can be any user metadata or technical facets.
  • values (mandatory): Defines the value for the given key. When multiple values are given, they are combined with an AND or an OR operator depending on the tenant configuration.
  • negative (optional): When set to true, the results matching the previously set values are excluded. By default, the negative parameter is implicit and set to false.
Defaults to empty list.
sort Array No Enables to specify a custom sort on any metadata.

The sort object expects the following criteria:
  • key (mandatory): Sort criterion keys can be any user metadata or technical facets, for example:
    • ft:lastPublication
    • ft:topicTitle
    • ft:relevance is a special keyword is provided to sort by relevance.
  • order (mandatory): Each criterion can be ascendant (ASC) or descendant (DESC). By default, the standard Fluid Topics sort order is used.
facets Array No Displays facets from their facet ID. Users can then filter content through these facets.

Facets are displayed in the same order as they are declared.

If facets is absent or present but empty, no facet is displayed.

The facet object expects the following criteria:

  1. id (mandatory): Is the facet ID.
  2. maxDepth (optional): Defines the maximum depth level for the facet. When displaying a hierarchical facet, by default, the whole hierarchy is displayed.
lastModified Object No Restricts results to those with a value for the ft:lastTechChange metadata that is within the specified period.
    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.
paging Object No Expects the following paging information:
  • page (mandatory): Is the number of the queried result page.
  • perPage (optional): Is the number of result clusters for each page.
By default, the pagination is set to page 1 and 20 results per page.

Response body

{
  "spellcheck": {
    "suggestedQuery": "metadata",
    "htmlSuggestedQuery": "<span class=\"kwicmatch\">metadata</span>"
  },
  "facets": [
    {
      "key": "ft:isPublication",
      "label": "ft:isPublication",
      "hierarchical": false,
      "multiSelectionable": true,
      "rootNodes": [
        {
          "value": "John Doe",
          "label": "John Doe",
          "selected": false,
          "totalResultsCount": 19,
          "childNodes": [],
          "descendantSelected": false
        },
        {
          "value": "Paul Dupont",
          "label": "Paul Dupont",
          "selected": false,
          "totalResultsCount": 8,
          "childNodes": [],
          "descendantSelected": false
        }
      ]
    }
  ],
  "results": [
    {
      "mapId": "qT_JLCMeNICKqt7tLEWRdg",
      "mapTitle": "Integrate the Fluid Topics API",
      "occurrences": [
        {
          "tocId": "P4gRbk8npq~xsOfvIMH6Vg",
          "readerUrl": "http://my_site.fluidtopics.net/r/Integrate-the-Fluid-Topics-API/Events/Analytics-events/Topic-events/topic.unrate",
          "breadcrumb": [
            "Events",
            "Analytics events",
            "Topic events",
            "topic.unrate"
          ]
        }
      ],
      "contentId": "yYqIvTEE47_eIK4MGSfoKQ",
      "topicUrl": "http://my_site.fluidtopics.net/api/khub/maps/2qCoH7U~z73O75bH4NoYbw/topics/yYqIvTEE47_eIK4MGSfoKQ",
      "contentUrl": "http://my_site.fluidtopics.net/api/khub/maps/2qCoH7U~z73O75bH4NoYbw/topics/yYqIvTEE47_eIK4MGSfoKQ/content",
      "htmlTitle": "<span class=\"kwicstring\">topic.unrate</span>",
      "htmlExcerpt": "<span class=\"kwictruncate\">...</span><span class=\"kwicstring\">contains its tocId and title . document An object containing information about the document.      id The document&#x27;s identifier.      </span><span class=\"kwicmatch\">metadata</span><span class=\"kwicstring\"> A list of the document&#x27;s </span><span class=\"kwicmatch\">metadata</span><span class=\"kwicstring\"> with the label and values of each key.      title The title of the document.      type The document&#x27;s type (</span><span class=\"kwictruncate\">...</span>",
      "metadata": [
        {
          "key": "category",
          "label": "Category",
          "values": [
            "Reference Guides"
          ]
        },
        {
          "key": "version",
          "label": "Version",
          "values": [
            "1.0"
          ]
        }
      ],
      "resources": [
        {
          "id": "I0uufqIcCMdfLNXUGSTDYw",
          "filename": "update_mode.png",
          "mimeType": "image/png",
          "viewerUrl": "http://my_site.fluidtopics.net/viewer/attachment/ENQRHyDq~oYAqQn5tJAjKA/I0uufqIcCMdfLNXUGSTDYw",
          "resourceUrl": "http://my_site.fluidtopics.net/api/khub/maps/ENQRHyDq~oYAqQn5tJAjKA/resources/I0uufqIcCMdfLNXUGSTDYw",
          "resourceContentUrl": "http://my_site.fluidtopics.net/api/khub/maps/ENQRHyDq~oYAqQn5tJAjKA/resources/I0uufqIcCMdfLNXUGSTDYw/content"
        }
      ]
    }
  ],
  "paging": {
    "currentPage": 1,
    "lastPage": false,
    "totalResultsCount": 850
  }
}

Where:

  • kwicstring is the part of the original query which was correctly spelled.
  • kwicmatch is the part of the query corrected by the spellchecker.