Destination

Data consumption in Occtoo involves retrieving and utilizing data from various custom destinations. Occtoo allows users to create destinations in Occtoo Studio, specifying properties such as identifier, languages, regions, and endpoints. These destinations can be either public — accessible via a unique URL without authentication — or protected, requiring an access token. Users can fetch destination data using various filtering and querying capabilities provided by the Occtoo API. This flexibility enables efficient data retrieval tailored to specific needs, supporting a wide range of use cases and integrations.

Destination API consumption

A destination comprises one or more endpoints for data retrieval. Each endpoint supports both GET and POST methods. These request methods offer various filtering options, allowing users to customize the response according to their needs. Several query parameters are available, all of which are optional. If no parameters are specified, the API fetches the first 50 results by default.

OpenAPI documentation

All destinations provide an OpenAPI URL. This URL allows users to view and test the various endpoints exposed by the destination. The OpenAPI specification URL is formed by combining the destination’s base URL with the suffix ‘/openapi’.

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.

Unprotected and protected destinations

A destination can be either unprotected or protected. An unprotected destination is public, meaning it is available to anyone with access to the URL and does not require authentication. Protected destinations, on the other hand, restrict access to authorized users only, ensuring that sensitive data and functionalities are secure. Authentication for protected destinations is done using an access token.

Token endpoint

The token endpoint is bundled with the destination and is accessed via a POST request. Upon passing valid credentials, a token is returned. This token remains valid for 24 hours from its creation and can be reused an unlimited number of times within that timeframe.

https://destinations.occtoo.com/destinations/{@DESTINATION-ID}/token

There is a rate limit of 100 token requests per hour for an application, so it is highly recommended to employ mechanisms to store and reuse the received token for the time period it is valid. If the rate limit is exceeded the token endpoint will respond with a 429 HTTP response. The 429 response contains a Retry-After header which gives an indication when the rate limit is reset.

Request payload

The tokens endpoint accepts a JSON payload in the body, consisting of the properties clientId and clientSecret. These properties correspond to the identifiers provided by the application used to access the destination.

{
    "clientId" : "{@APPLICATION-ID}",
    "clientSecret": "{@APPLICATION-SECRET}"
}

Response payload

Upon successful authentication of the passed credentials, an access token is returned from the API using the format below.

{
    "accessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im9jY3Rvby1jb20iLCJ0eXAiOiJhdCtqd3QifQ.eyJuYmYiOjE3MTc1MDg4MjYsImV4cCI6MTcxNzUxMjQyNiwiaXNzIjoiaHR0cHM6Ly9hdXRoLXRlc3Qub2NjdG9vLmNvbSIsImF1ZCI6IjhjZDQ1NjBmLWI4NjctNGQ3YS1hOTcyLWEzNTVjZDVjMjZkNyIsImNsaWVudF9pZCI6ImRlNTAwNjYyLTkwZmMtNDY2OC1hOGI0LTgwMmNiZjQwMTY4MCIsImNsaWVudF9yZXNvdXJjZSI6IjhjZDQ1NjBmLWI4NjctNGQ3YS1hOTcyLWEzNTVjZDVjMjZkNyIsImp0aSI6IjNFMDdENzgyM0E3MjBEQkVCNDQ0NzI4NzRFRkQ3Qzc2IiwiaWF0IjoxNzE3NTA4ODI2LCJzY29wZSI6WyI4Y2Q0NTYwZi1iODY3LTRkN2EtYTk3Mi1hMzU1Y2Q1YzI2ZDciXX0.gP2mMFFEYF4Pp1nw_UESdZpK9be8VnX1DCL_jIgZKdaF2rHG4nHT4PDDoV6W3V9A8pYI3HiVMZk7tEAn4WvPU5qzL-ayLiYD8DnGD7X5TpipGJ3cX7cZOZvqKzR7Kvx9affgbMZw7mBEJgnkrw6mDCRAt_6jJIo33AQMjD-oyFOFEn-xCmUnABwLw7sldiCQNRTDVQ_uFCWgePPeb3iAGEJd8Yh0oKUsfuuGBpSeBJtlLM-s5ts-2BNXYweUpP6MUIiC746EVVfcMdoTdzLEjkwpddScLacT-QI54E7zN00U4dlIS4uWoRLUvnZoczNlG_kyryckDTnz_LV5897N_Q",
    "expiresIn": 3600
}

Accessing a protected destination

To access a protected destination API, users must use the obtained access token as a bearer token. The bearer token must be included in the authorization header of every API request, formatted as “Authorization: Bearer access token”. The API validates this token to verify the application’s identity and permissions, granting access only if the token is valid and unexpired.

Request response compression

Gzip compression is a widely used method for reducing the size of data transmitted over networks, resulting in faster loading times and reduced bandwidth usage. In the context of Occtoo destinations, gzip compression is enabled to further optimize data retrieval processes. However, it is an opt-in feature, meaning callers can enable it by defining the ‘Accept-Encoding’ property in the HTTP header and setting its value to ‘gzip’. This instructs the server to compress the response data before sending it to the caller, enhancing performance and efficiency in data retrieval tasks.

curl --location 'https://global.occtoo.com/exampletenant/exampledestination/v1/exampleendpoint' \
--header 'Accept-Encoding: gzip' \
--header 'Authorization: Bearer {@DESTINATION-ACCESS-TOKEN}'

Facets aid in building navigation features by marking certain fields as facets. This allows retrieval of all values for those fields given a filter, along with the total count for each value. When adding a facet, you need to specify the property and the maximum number of facet values to retrieve for that property. Additionally, you can set a localized label for the facet header, which is useful 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"
        }
      ]
    }
 ]

Filtering

All properties can be filtered, though the syntax varies depending on the type of property. To see the different types for a specific endpoint, an OpenAPI URL is generated as described in the Documentation section.

GET filtering

When using the GET method, all comparisons are performed using the EQUAL operator. It is possible to filter on different properties in a single query, utilizing the AND comparison. Additionally, filtering on multiple values for one property is achieved using an OR comparison.

Filter on two different properties
Filter on two different values for one property (OR)

https://{@DESTINATION-ENDPOINT-ADDRESS}?brand=BrandA&category=Category1

https://{@DESTINATION-ENDPOINT-ADDRESS}?brand=BrandA&brand=BrandB

POST filtering

Within the POST body, a ‘filter’ can be supplied to reduce the number of returned results. The filter may be empty. However, nested content (object arrays) within each result cannot be filtered. The filter contains a list of queries, any one of which 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 matches the ID of the property in the result. All criteria within the same query must be met.

Example

Must filter on two values
Must and must not filters combined

Include only results for market “DE” OR “FI”.

{
  "filter": [
    {
      "must":{
        "market":["DE", "FI"]
      }
    }
  ]
}

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. Various 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 of property values 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"]
        }
      }
    }
  ]
}

When a result has a property with multiple values, and 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 that include tags “A” AND “B”.

{
  "filter": [
    {
      "must":{
        "tags": {
          "operator": "Equal",
          "values": ["A", "B"],
          "match": "All"
        }
      }
    }
  ]
}

In cases where exact matching of filter values is not very useful, Range-style criteria are available using separate “operators” for DateTime, Integer, and Double properties. Range operators:

GreaterThan
GreaterThanOrEqual
LessThan
LessThanOrEqual
Between
BetweenInclusive

Example

Include only results whose price is greater than 15.0.

{
  "filter": [
    {
      "must":{
          "price": {
            "operator": "GreaterThan",
            "values": [15.0]
          }
      }
    }
  ]
}

Include only results whose price is greater than or equal to 15.0.

{
  "filter": [
    {
      "must":{
          "price": {
            "operator": "GreaterThanOrEqual",
            "values": [15.0]
          }
      }
    }
  ]
}

Include only results whose price is less than 15.0.

{
  "filter": [
    {
      "must":{
          "price": {
            "operator": "LessThan",
            "values": [15.0]
          }
      }
    }
  ]
}

Include only results whose price is less than or equal to 15.0.

{
  "filter": [
    {
      "must":{
          "price": {
            "operator": "LessThanOrEqual",
            "values": [15.0]
          }
      }
    }
  ]
}

Include only results whose price is greater than 15.0 but less than 20.0.

{
  "filter": [
    {
      "must":{
          "price": {
            "operator": "Between",
            "values": [15.0, 20.0]
          }
      }
    }
  ]
}

Include only results whose price is at least 15.0 and at most 20.0.

{
  "filter": [
    {
      "must":{
          "price": {
            "operator": "BetweenInclusive",
            "values": [15.0, 20.0]
          }
      }
    }
  ]
}

API query parameters

id

Type: string (array) Get one or multiple entries by ID.

GET
POST

For the GET request the ID parameter can be repeated to get multiple entries at once.

https://{@DESTINATION-ENDPOINT-ADDRESS}?id=id1

The POST request uses the filter syntax and can be combined freely with other filters to specifically include or exclude IDs.

// Payload body

//To include only specific ids
{
  "filter": [{
    "must": { "id": ["id1", "id2", "id3"] }
  }]
}

//To exclude specific ids
{
  "filter": [{
    "must_not": { "id": ["id1", "id2", "id3"] }
  }]
}

select

Type: string (array) Return only the specified properties for each entry instead of the full result object. This reduces the response size and is useful when a client only needs a few properties from an endpoint that exposes many. The property names are the ones exposed by the endpoint, meaning the alias if one is configured. If ‘select’ is omitted, all properties configured on the endpoint are returned. For the GET request, the ‘select’ parameter can be repeated to return multiple properties at once. For the POST request, an array of one or more property names is required.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?select=propertyA&select=propertyB

//Payload body
{
  "select": ["propertyA", "propertyB"]
}

‘Select’ can be combined freely with filtering, sorting, and searching — those operate on all properties of the endpoint, not just the selected ones. If only the IDs of the entries are needed, use listIds instead.

listIds

Type: boolean This allows for an efficient way to retrieve 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
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?listIds=true

// Payload body

{
    "listIds": true
}

includeTotals

Type: boolean Includes the total number of results for the query in the response. However, it has a negative impact on request performance that increases with the number of entries.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?includeTotals=true

//Payload body
{
    "includeTotals": true
}

includeMeta

Type: boolean Include a ‘meta’ section for each entry in the response. This section contains information about when the entry was last updated, its type, language, and ID. The timestamp is in UTC datetime format.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?includeMeta=true

//Payload body
{
  "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 Retrieve the top x number of entries from the endpoint. This can be used together with skip for implementing pagination. The maximum number of entries to retrieve with ‘top’ and ‘skip’ is 10 000.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?top=100

// Payload body
{
  "top": 100
}

skip

Type: int32 Skip x number of entries in the request. This can be used together with top for implementing pagination. The maximum number of entries to retrieve with ‘top’ and ‘skip’ is 10 000.

GET
POST

GET https://{@DESTINATION-ENDPOINT-ADDRESS}?skip=10

//Payload body
{
  "skip": 10
}

The maximum number of entries to retrieve with top and skip is 10 000. If more results are needed, use after.

after

Type: string (array) ‘After’ is used together with sorting and allows for getting the entries after the provided value for the specified sorting property. It 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. A maximum of 10 000 entries can be returned from ‘top’.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?after=id123&sortAsc=id

//Payload body
{
  "after": "id123",
  "sortAsc": ["id"]
}

sortAsc

Type: string (array) To sort a property in ascending order, use the ‘sortAsc’ parameter. For the GET request, the ‘sortAsc’ parameter can be repeated to sort on multiple properties at once. For the POST request, an array of one or more sort properties is required.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?sortAsc=propertyA

//Payload body
{
  "sortAsc": ["propertyA"]
}

sortDesc

Type: string (array) To sort a property in descending order, use the ‘sortDesc’ parameter. For the GET request, the ‘sortDesc’ parameter can be repeated to sort on multiple properties at once. For the POST request, an array of one or more sort properties is required.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?sortDesc=propertyA

//Payload body
{
  "sortDesc": ["propertyA"]
}

language

Type: string Specify requested language.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?language=languageCode

//Payload body
{
  "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 request results as multiples of the number of languages.

search

Type: string (array) To search property values matching the specified phrase, use the ‘search’ parameter. This is used together with ‘searchOn’ to specify which properties to search on. It matches the entire search phrase, but the character ’*’ can be used for wildcard search. For instance, ‘*value’ is equivalent to ‘ends with value’, ‘value*’ is equivalent to ‘begins with value’, and ‘*value*’ is equivalent to ‘contains value’. For the GET request, the ‘search’ parameter can be repeated to search on multiple phrases at once. For the POST request, an array of one or more search properties is required. If multiple phrases are provided, they will be combined using AND logic.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?search=phrase

//Payload body
{
  "search": ["phrase"]
}

searchOn

Type: string (array) To specify the properties to search on, use the ‘searchOn’ parameter. For the GET request, the ‘searchOn’ parameter can be repeated to search on multiple properties at once. For the POST request, an array of one or more search properties is required.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?searchOn=property

//Payload body
{
  "searchOn": ["property"]
}

caseInsensitiveSearch

Type: boolean By default, the search is case sensitive. To perform a case insensitive search, set the flag ‘caseInsensitiveSearch’ to true.

GET
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?caseInsensitiveSearch=true

//Payload body
{
  "caseInsensitiveSearch": true
}

periodSince

Type: datetime Retrieve 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
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?periodSince=2022-07-26T17:54:19.7458504Z

//Payload body
{
  "period": 
  {
    "since" : "2022-07-26T17:54:19.7458504Z"
  }
}

periodBefore

Type: datetime Retrieve 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
POST

https://{@DESTINATION-ENDPOINT-ADDRESS}?periodBefore=2022-07-26T17:54:19.7458504Z

//Payload body
{
  "period": 
  {
    "before" : "2022-07-26T17:54:19.7458504Z"
  }
}

The parameter ‘periodSince’ can be combined with ‘periodBefore’ to get all updates within a specific range.

API response

The structure of the response object remains consistent whether it’s a POST or a GET request. It always includes the language being retrieved and an array of result objects. If there are no results, an empty array is returned. The result objects vary between endpoints and destinations, as they are configured individually. To view the structure of a specific endpoint, an OpenAPI URL is generated, as described in the OpenAPI documentation section. If the API parameter select is used, each result object contains only the requested properties. If the endpoint contains facets, they are included as an array. The structure of the facet response is described under facets. If facets are not configured, the “facets” property is omitted from the response. The “total” property indicates the total number of results and is only included in the response 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" : []
}

Getting started

Application authentication

Ingest API

Events API

Data consumption

Destination API consumption

OpenAPI documentation

Unprotected and protected destinations

Token endpoint

Request payload

Response payload

Accessing a protected destination

Request response compression

Facets

Filtering

GET filtering

POST filtering

Example

Example

Example

Example

API query parameters

id

select

listIds

includeTotals

includeMeta

top

skip

after

sortAsc

sortDesc

language

search

searchOn

caseInsensitiveSearch

periodSince

periodBefore

API response

​Destination API consumption

​OpenAPI documentation

​Unprotected and protected destinations

​Token endpoint

Request payload

Response payload

​Accessing a protected destination

​Request response compression

​Facets

​Filtering

​GET filtering

​POST filtering

Example

Example

Example

Example

​API query parameters

​id

​select

​listIds

​includeTotals

​includeMeta

​top

​skip

​after

​sortAsc

​sortDesc

​language

​search

​searchOn

​caseInsensitiveSearch

​periodSince

​periodBefore

​API response

Destination API consumption

OpenAPI documentation

Unprotected and protected destinations

Token endpoint

Accessing a protected destination

Request response compression

Facets

Filtering

GET filtering

POST filtering

API query parameters

id

select

listIds

includeTotals

includeMeta

top

skip

after

sortAsc

sortDesc

language

search

searchOn

caseInsensitiveSearch

periodSince

periodBefore

API response