Searching and querying

Introduction

There are numerous ways to filter out data when querying the API. An easy approach using a query parameter filter and a more flexible one using a query object. Either way, it is important to try to retrieve relevant data instead of everything all the time, in order to save resources and network traffic.

Retrieving the delta (changes)

Using lastModifiedAtOrAfter query parameter is strongly encouraged when polling for new/changed data in any endpoint. All records in the Integration Platform have a lastModified field with timestamp (Date time) indicating exactly when that record was changed within the Integration Platform. By using the query parameter lastModifiedAtOrAfter you will only receive relevant information when polling for changes.

Search query

Some endpoints have support for more flexible search query, e.g POST /product/query. The query is sent as an JSON object in the request body. See the complete specification in the Swagger API reference.

The query consists of a filter which can contain a search for a specific field, or it can be an and/or-operator which contains a list of other filters. The Swagger API reference will define available fields for a specific endpoint.

Example of a filter on lastModified

This filter will return records number 11 to 20 where lastModified is greater than 2015-01-02T03:04:05Z and the result is ordered in an ascending order based on the field lastModified.

{
  "filter": {
    "type": "gt",
    "field": "lastModified",
    "value": {
      "type": "datetime",
      "value": "2015-01-02T03:04:05Z"
    }
  },
  "order": [
    {
      "field": "lastModified",
      "direction": "ascending"
    }
  ],
  "numRecords": 10,
  "offset": 10
}

Example of a filter that contains subclauses

This filter will get records where lastModified is greater than 2015-01-02T03:04:05Z OR if the field sku is equal to 1001. The maximum returned records is set by the numRecords.

{
  "filter": {
    "type":"or",
    "subclauses":[
      {
        "type": "gt",
        "field": "lastModified",
        "value": {
          "type": "datetime",
          "value": "2020-12-22T06:24:57Z"
        }
      },
      {
        "type": "eq",
        "field": "sku",
        "value": {
          "type": "str",
          "value": "1001"
        }
      }
    ]
  },
  "numRecords":100
}

Example of a filter on remoteId for a connectionId

This filter will get records the connectionId 3fb2568eb7e165e34dd311af5550002b has the remoteId a remoteId. RemoteId set per connection see section RemoteId

{
  "filter": {
    "type": "remoteId",
    "connectionId":"3fb2568eb7e165e34dd311af5550002b",
    "remoteId":"a remoteId"
  }
}