Skip to main content

Data consumption

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. 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
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.

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 60 minutes from its creation and can be reused an unlimited number of times within that timeframe.

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

Since the number of possible requests to the token endpoint for a single application is limited, it is highly recommended to employ mechanisms to store and reuse the received token for the time period it is valid.

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 applications'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/exampeltenant/exampeldestination/v1/exampelendpoint' \
--header 'Accept-Encoding: gzip' \
--header 'Authorization: Bearer {@DESTINATION-ACCESS-TOKEN}'

Facets​

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.

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

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.

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

POST filtering​

Within the POST body, a 'filter' can be supplied to reduce the amount 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​

Include only results for market "DE" OR "FI".

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

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 values of properties are 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 which 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 which price is greater than 15.0.

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

API query parameters​

id​

Type: string (array)

Get one or multiple entries by ID.

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

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

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.

https://{@DESTINATION-ENDPOINT-ADDRESS}?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.

https://{@DESTINATION-ENDPOINT-ADDRESS}?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.

https://{@DESTINATION-ENDPOINT-ADDRESS}?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 amount of entries from the endpoint. This can be used together with skip for implementing pagination. The maximum amount of entries to retrieve with 'top' and 'skip' is 10 000.

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

skip​

Type: int32

Skip x amount of entries in the request. This can be used together with top for implementing pagination. The maximum amount of entries to retrieve with 'top' and 'skip' is 10 000.

GET https://{@DESTINATION-ENDPOINT-ADDRESS}?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 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'.

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

sortAsc​

Type: string (array)

To sort 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.

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

sortDesc​

Type: string (array)

To sort 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.

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

language​

Type: string

Specify requested language.

https://{@DESTINATION-ENDPOINT-ADDRESS}?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 request results as multiples of the number of languages.

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.

https://{@DESTINATION-ENDPOINT-ADDRESS}?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.

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

caseInsensitiveSearch​

Type: boolean

By default, the search is case sensitive. To perform a case insensitive search, set the flag 'caseInsensitiveSearch' to true.

https://{@DESTINATION-ENDPOINT-ADDRESS}?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.

https://{@DESTINATION-ENDPOINT-ADDRESS}?periodSince=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.

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

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 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 "facet" 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" : []
}