...
Code Block |
---|
search: text: The text to search for in your content |
It will return
This very open query will return a JSON containing the contents of all content items (with a limit) matching the text in all languages, in this form:
Code Block |
---|
{
"results" : [ {
"_searchRetrieve" : {
"contentItemID" : "M123",
"language" : "nl_NL",
"success" : true
},
... JSON contents of the first result ...
}, {
"_searchRetrieve" : {
"contentItemID" : "P12345",
"language" : "en_US",
"success" : true
},
... JSON contents of the first result ...
} ]
} |
Prerequisites for testing this yourselfPrerequisites: XperienCentral R32+ or R27+ with the Headless Add-on upgraded to version 2.2.5+. The checkbox search_retrieve_enabled needs to be checked in the Setup tool.
Tooling: A free tool for sending such requests is Postman.
More example queries
Let's have a look at two more examples to give you an idea of how to work with the API. The examples are written as YAML, but also JSON is supported. (On json2yaml.com you can easily convert between the two formats.)
Get results 11 to 20 of content items in Dutch with the keywords (=tags, labels, terms) news and sports.
Code Block |
---|
search:
keywordsAnd:
- news
- sports
languages:
- en_US
from: 11
to: 20
|
Find the Dutch content item versions for the content items with ID M1 and P26111
Code Block |
---|
search:
ids:
- M123
- P12345
languages:
- nl |
Releases and work in progress
The first version of the Search and Retrieve API is released with XperienCentral R32 on May 10, 2021. It contains the functionalities described here and is intended as a release to be used during development but it is discouraged to use it in production. In the first few weeks after that release, major functionalities will be added to make it production ready. Notice that the Headless add-on which contains this functionality can be upgraded without upgrading XperienCentral. Features to be added:
- Rate limitations to protect the server from Denial of Service attacks ("DDos") and other security enhancements.
- Including referenced items in the response.
- Field filtering to only keep relevant fields in the response.
- Support for more kinds of search criteria, including custom fields.
If you have access to our Jira issue tracking system, see this issue and its sub-tasks for all technical details.
Misc - TODO
- For media items, the display-on page version in the media item language will always be used, also when the media item fallbacks to another language than the requested one.
Settings
TODO: One setting
...
Parameter name | Description | Example (yaml) | Example (json) |
---|---|---|---|
ids | Search for a content item using the item's content ID (Note: NOT the content item version ID). When you are looking for a Page the ID needs to be prefixed with a P, when looking for a media item the ID should be prefixed with an M. So for example for a page it would be P26111 and for a media item it would be M1. This parameter can be used to together with the languages parameter in order to retrieve the correct version. It can not be used in combination with any other parameter. When other parameters besides ids and languages are provided they will be ignored. | search: | { |
languages | By adding this parameter to the request you can control in which language you want the results to be returned. This parameter supports both the short country code metatag value (ISO-639) as well as the full meta tag value (ISO-639 and ISO-3166 separated by an underscore "_"). Please note that when the full metatag value is provided, just the country code will be used, due to a limitation within the content index. This will be fixed in a later XperienCentral release. The languages parameter can be used in combination with both ID based queries and parameterized queries. If this parameter is omitted the active version for each available language will be returned. If there is no active version available, no version will be returned. | search: | { |
text | This field can be used to search for any text in the title or the body of the documents in the content index. | search: | { |
keywordsAnd | Add a list of terms to the query. The results have to contain all the listed terms. | search: | { |
keywordsOr | Add a list of terms to the query. The results have to contain one or more of the terms specified. | search: keywordsOr: - term 1 - term 2 | { |
keywordsNot | Add a list of terms to the query. The results may not contain any of the listed terms. | search: | { |
keywordCategories | Add a list of term categories to the query. The result has to contain at least one term that is in one of the provided categories. | search: | { |
from | Allows the selection of a subset of the results starting at the value of this parameter. The first result in a result set has index 1, so the from parameter should always be 1 or higher. Also note that this parameter is inclusive, meaning that when from is 3, the result set will include the third result and onwards. When omitted the value 1 will be used. | search: | { |
to | Allows the selection of a subset of the results ending at the value of this parameter. Like the from parameter this parameter is inclusive, meaning that when to is set to 1, only the first result will be returned. When from is set to 3 and to is set to 5 the results 3, 4 and 5 will be returned. Like from the minimum value for this parameter is 1. When omitted a maximum number of 100 results will be returned, starting at the from parameter if provided, 1 otherwise. | search: | { |
Example queries
Find the first 10 articles in Dutch with the term "term 1".
Code Block |
---|
search:
languages:
- nl
keywordsAnd:
- term 1
from: 1
to: 10
|
Find the Dutch content item versions for the content items with ID M1 and P26111
Code Block |
---|
search:
ids:
- M1
- P26111
languages:
- nl |
Find any content item version that contains the text lore
...