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​

For POST filtering it is possible to specify operators depending on the property type of data. The filtering property takes an array of filters, and the filters are combined using the OR comparison. Each filter is specified with 'must' or 'must_not', where 'must' require a match and 'must_not' requires there is no match. The filter consists of one or more critera, complex or simple. Multiple criteria are combined used the AND comparison. The simple criteria takes a property id and an array of values. The values are matched using the Equal operator, and if more than one value is provided an OR comparison is used between the values. The complex criteria takes a property id and an object containing the operator and the values. The possible operators depends on the data type of property being filtered.

The different data types available are:

  • 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

The operators that can be specified depending on data type:

  • Equal - can be used for all data types
  • GreaterThan - can be used for dates, integers, and doubles
  • GreaterThanOrEqual - can be used for dates, integers, and doubles
  • LessThan - can be used for dates, integers, and doubles
  • LessThanOrEqual - can be used for dates, integers, and doubles
  • Between - can be used for dates, integers, and doubles
  • BetweenInclusive - can be used for dates, integers, and doubles
// POST Filter syntax
{
  "filter": [
    {
      // multiple criteria => AND
      "must|must_not":{
          "propertyA":["value 1", "value 2"], //Simple criteria. Multiple values => OR
          "propertyB": {"operator": "operator", "values": ["value"]} // Complex criteria
      }
    }
  ]
}

// example of query with multiple filters and where the second filter has both simple and complex criteria
{
  "top": 10,
  "searchOn": ["name", "description"],
  "search": ["*jacket*", "*trousers*"],
  "filter": [ // multiple filters => OR
    {
      "must": {"assortment": ["EU"], "brand": ["Apparel"]},
      "must_not": {"assortment": ["DE"], "articleNo": ["381506"]}
    },
    {
      "must": { "assortment": ["DE"], "brand": ["Apparel"],
                "price": {  "operator": "LessThan",  "values": [100] } 
              }
    }
  ]
}

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