Skip to main content

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

tip

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.

An image from the static

caution

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}
tip

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"}
tip

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.

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"}}
tip

The parameter periodSince be combined with periodBefore to get all updates within a specific range