Fetch destination data
A destination consists of one more endpoints for fetching data. Each endpoint has one GET and one POST method (when should you use which). There are several query parameters than can be used and none of them are required. If no parameters are provided the first 50 results are fetched.
Documentation
All destinations expose an OpenAPI URL. This can be used to view and try the different endpoints exposed by the destination. The URL to the OpenAPI specification is the destination base URL together with the suffix '/openapi'.
/*Example OpenAPI URL*/
https://global.occtoo.com/customer/destination/v1/openapi
To try the feature go to https://editor-next.swagger.io/. From the menu select 'File' => 'Import URL' and enter the OpenAPI URL to see and test the destination. If it is a protected destination, client id and secret need to be provided.
Facets
Facets are way to help build navigation features. By marking certain fields as facets it is possible to retrieve all values for the fields given the filter, as well as the total number of each value. When adding a facet the property needs be specified as well as the maximum number of facet values to retrieve for the property. It is also possible to set a localized label for the facet header. This can be used when presenting the values in a UI.
Adding a facet size above 50 can have a negative effect on response times
/*Example facet response*/
"facets": [
{
"propertyId": "category",
"header": "Category",
"values": [
{
"count": 1,
"key": "Category 1"
},
{
"count": 83,
"key": "Category 2"
}
]
},
{
"propertyId": "brand",
"header": "Brand",
"values": [
{
"count": 3,
"key": "Brand A"
},
{
"count": 6,
"key": "Brand B"
}
]
}
]
Response
The structure of the response object looks the same regardless if it is a POST request or a GET request. The response always returns the language that is being retrieved and an array of result objects. If there are no results an empty array is returned. The result objects will be different between endpoints and destinations, as they are configured individually. To view the structure of a specific endpoint there is an OpenAPI URL generated as described in the section Documentation
Should the endpoint contain facets they are included as an array. The structure of the facet response is described under facets. If facets are not configured the facet property is omitted from the response. The 'total' property shows the total number of results and is only included in the result if the API parameter includeTotals is present and set to true. If the parameter is not present the 'total' property is omitted from the response.
{
"language": "en",
"total": 1847,
"results": [],
"facets" : []
}
Filtering
All properties can be filtered, however the syntax will differ depending on the type of a property. To view the different types for a specific endpoint there is an OpenAPI URL generated as described in the section Documentation
GET filtering
When using the GET method all comparision is done using the EQUAL operator. It is possible to filter on different properties in one query and it is also possible to filter on multiple values for one property. Filtering on different properties is using the AND comparison, and when multiple values are provided for one property an OR comparsion is made.
// Filter on two different properties
GET https://[@endpoint]?brand=BrandA&category=Category1
// Filter on two different values for one property (OR)
GET https://[@endpoint]?brand=BrandA&brand=BrandB
POST filtering
Within the POST body a 'filter' must be supplied to reduce the amount of returned results. The filter may be empty. Nested content (object arrays) within each result may not be filtered.
The filter contains a list of queries of which ANY one must be fulfilled. Each query may include criteria for inclusion 'must', exclusion 'must_not' or both. Criteria are expressed as properties of the criteria, where the id of the property matches the id of the property in the result.
All criteria within the same query must be met.
Example
Include only results for market "DE" OR "FI".
{
"filter": [
{
"must":{
"market":["DE", "FI"]
}
}
]
}
Example
Include only results for market "DE", "FI" OR "UK". For markets "DE", "FI" additionally exclude results of type "ExcludeThisTypeForDEAndFI".
{
"filter": [
{
"must":{
"market":["DE", "FI"]
},
"must_not":{
"type":["ExcludeThisTypeForDEAndFI"]
}
},
{
"must":{
"market":["UK"]
}
}
]
}
Filter values are always passed as arrays of values. The following data types are available for filter values, matching the data type of the property in the result:
- String - regular string value
- Datetime - format yyyy-MM-dd'T'HH:mm:ss.SSSSSSSZ. No UTC conversion is done on the data.
- Integer - regular integer value
- Double - uses '.' as a decimal separator
- Bool - possible values are true/false
Matching values of properties is performed using exact matches against ANY of the provided filter values.
Example
Alternate query syntax. These queries are the same.
{
"filter": [
{
"must":{
"market":["DE", "FI"]
}
},
{
"must":{
"market": {
"operator": "Equal",
"values": ["DE", "FI"]
}
}
}
]
}
In cases where a result has a property with multiple values where more than one value must match at once the standard OR between filter values can be replaced with an AND by using the "match" parameter set to "All" using the alternate criteria syntax.
Example
Include only results which include tags "A" AND "B".
{
"filter": [
{
"must":{
"tags": {
"operator": "Equal",
"values": ["A", "B"],
"match": "All"
}
}
}
]
}
For cases where exactly matching filter values is not super useful, Range style criteria are available using separate "operators", available for DateTime / Integer / Double properties.
Range operators:
- GreaterThan
- GreaterThanOrEqual
- LessThan
- LessThanOrEqual
- Between
- BetweenInclusive
Example
Include only results which price is greater than 15.0.
{
"filter": [
{
"must":{
"price": {
"operator": "GreaterThan",
"values": [15.0]
}
}
}
]
}
Example
Include only results which price is greater than or exactly 15.0.
{
"filter": [
{
"must":{
"price": {
"operator": "GreaterThanOrEqual",
"values": [15.0]
}
}
}
]
}
Example
Include only results which price is less than 15.0.
{
"filter": [
{
"must":{
"price": {
"operator": "LessThan",
"values": [15.0]
}
}
}
]
}
Example
Include only results which price is less than or exactly 15.0.
{
"filter": [
{
"must":{
"price": {
"operator": "LessThanOrEqual",
"values": [15.0]
}
}
}
]
}
Example
Include only results which price is greater than 15.0 but less than 20.0.
{
"filter": [
{
"must":{
"price": {
"operator": "Between",
"values": [15.0, 20.0]
}
}
}
]
}
Example
Include only results which price is greater than or exactly 15.0 but less than or exactly 20.0.
{
"filter": [
{
"must":{
"price": {
"operator": "BetweenInclusive",
"values": [15.0, 20.0]
}
}
}
]
}
API parameters
id
Type: string (array)
Get entry by id. For the GET request the id parameter can be repeated to get multiple entries at once.
GET https://[@endpoint]?id=id1
The POST request uses the filter syntax and can be combined freely with other filters to specifically include or exclude ids.
POST https://[@endpoint]
//To include only specific ids
{
"filter": [{
"must": { "id": ["id1", "id2", "id3"] }
}]
}
//To exclude specific ids
{
"filter": [{
"must_not": { "id": ["id1", "id2", "id3"] }
}]
}
listIds
Type: boolean
Allows for an efficient way to get the ids of the entries. No additional properties are returned. By default 50 ids are returned. If more results are needed it can be used together with top.
GET https://[@endpoint]?listIds=true
POST https://[@endpoint] {"listIds": true}
includeTotals
Type: boolean
Includes the total number of results for the query in the response. It has a negative impact on request performance that increase with the number of entries.
GET https://[@endpoint]?includeTotals=true
POST https://[@endpoint] {"includeTotals": true}
includeMeta
Type: boolean
Include meta section for each entry in the response. The section contains information about when the entry was last updated, type, language and the id. The timestamp is in UTC date time format.
GET https://[@endpoint]?includeMeta=true
POST https://[@endpoint] {"includeMeta": true}
//Example of meta data payload included on each result entry
"@meta": {
"@timestamp": "2022-07-26T16:12:19.6882765Z",
"@id": "74a7d309",
"@type": "SomeCardType",
"@language": "en"
}
top
Type: int32
Get top x amount of entries from the endpoint. Can be used together with skip for implementing pagination. The maximum amount of entries to retrieve with top and skip is 10 000.
GET https://[@endpoint]?top=100
POST https://[@endpoint] {"top": 100}
skip
Type: int32
Skip x amount of entries in the request. Can be used together with top for implementing pagination. The maximum amount of entires to retrieve with top and skip is 10 000.
GET https://[@endpoint]?skip=10
POST https://[@endpoint] {"skip": 10}
The maximum amount of entires to retrieve with top and skip is 10 000. If more results are need use after.
after
Type: string (array)
After is used together with sorting and allows for getting the entries after the provided value, for the sorting property specified. Can be used together with either (sortAsc or sortDesc). By default 50 entries are returned. If more results are needed it can be used together with top. Maximum of 10 000 entries can be returned from top.
GET https://[@endpoint]?after=id123&sortAsc=id
POST https://[@endpoint] {"after": "id123","sortAsc": ["id"]}
sortAsc
Type: string (array)
Sort property in ascending order. For the GET request the sortAsc parameter can be repeated to sort on multiple properties at once. The POST request requires an array of one or more sort properties.
GET https://[@endpoint]?sortAsc=propertyA
POST https://[@endpoint] {"sortAsc": ["propertyA"]}
sortDesc
Type: string (array)
Sort property in descending order. For the GET request the sortDesc parameter can be repeated to sort on multiple properties at once. The POST request requires an array of one or more sort properties.
GET https://[@endpoint]?sortDesc=propertyA
POST https://[@endpoint] {"sortDesc": ["propertyA"]}
language
Type: string
Specify requested language.
GET https://[@endpoint]?language=languageCode
POST https://[@endpoint] {"language": "languageCode"}
To return values for all languages in one request the parameter can be set to all (?language=all). This will return one entry for each language. However, top limits still apply so make sure to get the results as multiple of the number of languages.
search
Type: string (array)
Search property values matching the specified phrase. Used together with searchOn to specify which properties to search on. Matches the entire search phrase, but character '*' can be used for wildcard search. For instance '*value' is the equivalent of 'endswith value', 'value*' is the equivalent of 'beginswith value', and '*value*' is the equivalent of contains. For the GET request the search parameter can be repeated to search on multiple phrases at once. The POST request requires an array of one or more search properties. If multiple phrases are provided they will be combined using AND.
GET https://[@endpoint]?search=phrase
POST https://[@endpoint] {"search": ["phrase"]}
searchOn
Type: string (array)
Specify the properties to search on. For the GET request the searchOn parameter can be repeated to search on multiple properties at once. The POST request requires an array of one or more search properties.
GET https://[@endpoint]?searchOn=property
POST https://[@endpoint] {"searchOn": ["property"]}
caseInsensitiveSearch
Type: boolean
By default the search is case sensitive. If case insensitive search is needed the flag caseInsensitiveSearch can be set to true.
GET https://[@endpoint]?caseInsensitiveSearch=true
POST https://[@endpoint] {"caseInsensitiveSearch": true}
periodSince
Type: datetime
Get all entries modified after the provided timestamp. All times are compared using UTC in the format yyyy-MM-dd'T'HH:mm:ss.SSSSSSSZ.
GET https://[@endpoint]?periodSince=2022-07-26T17:54:19.7458504Z
POST https://[@endpoint] {"period": { "since" : "2022-07-26T17:54:19.7458504Z"}}
periodBefore
Type: datetime
Get all entries modified before the provided timestamp. All times are compared using UTC in the format yyyy-MM-dd'T'HH:mm:ss.SSSSSSSZ.
GET https://[@endpoint]?periodBefore=2022-07-26T17:54:19.7458504Z
POST https://[@endpoint] {"period": { "before" : "2022-07-26T17:54:19.7458504Z"}}
The parameter periodSince be combined with periodBefore to get all updates within a specific range