This web service lets users search unstructured documents. It returns unclustered documents matching the query conditions through a paginated response.
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/documents/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 document's ft:lastTechChange metadata. 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. |
- It is possible to use pagination with this web service.
- Using pagination when searching documents 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 Query Manager failed to respond. |
Request body
The following lines display an example of a JSON request body:
{
"query": "$KEYWORDS",
"contentLocale": "$LOCALE",
"filters": [
{
"key": "$FACET_ID_1",
"values": [
"$FACET_VALUE_A",
"$FACET_VALUE_B"
]
},
{
"key": "$FACET_ID_2",
"values": [
"$FACET_VALUE_C"
]
}
],
"sort": [
{
"key": "$FACET_ID_1",
"order": "ASC"
},
{
"key": "$FACET_ID_2",
"order": "DESC"
}
],
"lastModified": {
"from": "2022-01-01",
"to": "2022-09-30"
},
"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, an empty search is queried. |
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, Fluid Topics replaces fr 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:
|
sort |
Array | No | Specifies a custom sort on any metadata. The sort object expects the following criteria:
|
facets |
Array | No | Display 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:
|
lastModified |
Object | No | Restricts results to those with a value for the ft:lastTechChange metadata that is in 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:
|
Response body
{
"spellcheck": {
"suggestedQuery": "correctedKeywords",
"htmlSuggestedQuery": "<span class=\"kwicmatch\">correctedKeywords</span>"
},
"facets": [
{
"key": "ft:isPublication",
"label": "ft:isPublication",
"hierarchical": false,
"multiSelectionable": true,
"rootNodes": [
{
"value": "true",
"label": "true",
"selected": false,
"totalResultsCount": 1,
"childNodes": [],
"descendantSelected": false
}
]
}
],
"results": [
{
"documentId": "wuq~8lXw7YHaFWfTkn~CFA",
"title": "Fluid Topics unstructured document Bar",
"htmlTitle": "... succession of <span> with .kwicstring or .kwicmatch CSS classes ...",
"htmlExcerpt": "... succession of <span> with .kwicstring or .kwicmatch CSS classes ...",
"filename": "bar-ud.jpg",
"mimeType": "image/jpeg",
"metadata": [
{
"key": "dataset",
"label": "dataset",
"values": [
"test-checking-publication-types"
]
},
{
"key": "cdata:openMode",
"label": "cdata:openMode",
"values": [
"fluidtopics"
]
}
],
"source": {
"id": "source_42",
"name": "My_source",
"type": "${source_type}",
"description": "This is the source through which I retrieve content"
},
"lastEditionDate": "2020-11-24",
"openMode": "FLUIDTOPICS",
"originUrl": "http://origin-url/...",
"documentUrl": "https://api.my_site.fluidtopics.net/khub/documents/:documentId/topics/:contentId",
"contentUrl": "https://api.my_site.fluidtopics.net/khub/documents/:documentId/content",
"viewerUrl": "http://my_site.fluidtopics.net/v/u/Fluid-Topics-unstructured-document-Bar"
}
],
"lastModified": {
"from": "2022-01-01",
"to": "2022-09-30"
},
"paging": {
"currentPage": 1,
"totalResultsCount": 1,
"isLastPage": true
}
}
Where:
kwicstring
is the part of the original query which was correctly spelled.kwicmatch
is the part of the query corrected by the spellchecker.