Skip to main content

Using the Search API

The request examples here are using the RFC 2616 format. Essentially the first line contains the HTTP Method and URL followed by the HTTP headers. There is then an empty line between the headers and the message body.

The Authorization:Bearer header is followed by the access token retrieved as described in the IoT Connect Authentication section.

Filtering Search Results​

Filtering search results are done using the filters property which can contain one or multiple entries. This example searches for subscriptions where iotSubscription.lastModifiedAt is between 2024-05-18T12:12:34.000Z and 2024-06-30T23:59:59.000Z

POST https://api.iot.telenor.com/iot-connect/subscription-inventory/v2/search
Content-Type:application/json
Accept:application/json
Authorization:Bearer [...]

{
  "filters": [
    {
      "fields": [
          "iotSubscription.lastModifiedAt"
      ],
      "type": "between",
      "values": {
          "min": "2024-05-18T12:12:34.000Z",
          "max": "2024-06-30T23:59:59.000Z"
      }
    }
  ]
}

Sorting and Pagination​

The search results can be ordered by one or more fields using the sortBy property. In this example subscriptions are returned ordered by iotSubscription.iotSubscriptionId in acending order.

POST https://api.iot.telenor.com/iot-connect/subscription-inventory/v2/search
Content-Type:application/json
Accept:application/json
Authorization:Bearer [...]

{
  "sortBy": [
    {
      "direction": "asc",
      "field": "iotSubscription.iotSubscriptionId"
    }
  ]
}

In every response a token for paginating to the next page of results is found within the pagination property next

{
  "pagination": {
    "totalHits": xxxx,
    "next": "PAGINATION_TOKEN"
  },
  "items": [ ... ]
}

The pagination token is a string that if provided in the request as the after property will result in the next page of results being returned

Note: The pagination token is valid for 2 minutes and every consequent request refreshes this with an additional 2 minutes. In essence the maximum time in between pagination requests where the token is still valid is 2 minutes.

Here's an example of a request returning the next page of result of the previous query

POST https://api.iot.telenor.com/iot-connect/subscription-inventory/v2/search
Content-Type:application/json
Accept:application/json
Authorization:Bearer [...]

{
  "after": "PAGINATION_TOKEN",
  "sortBy": [
    {
      "direction": "asc",
      "field": "iotSubscription.iotSubscriptionId"
    }
  ]
}

Every API call will return a new next property that will return the next page of results when provided as the after property in the next request.

Limiting the Number of Returned Results​

The number of returned subscriptions per request can be limited using the limit property. Here we are requesting only the top 5 results to be returned.

POST https://api.iot.telenor.com/iot-connect/subscription-inventory/v2/search
Content-Type:application/json
Accept:application/json
Authorization:Bearer [...]

{
    "limit": 5,
    "sortBy": [
        {
        "direction": "asc",
        "field": "iotSubscription.iotSubscriptionId"
        }
    ]
}

Specifying the Returned Subscription Fields​

In order to reduce the size of the search results it's possible to specify the fields returned for each subscription. This is done using the returnFields property. In this example the returned fields are limited to only iotSubscription.iotSubscriptionId, iotSubscription.subscriptionType and iotSubscription.domainId

POST https://api.iot.telenor.com/iot-connect/subscription-inventory/v2/search
Content-Type:application/json
Accept:application/json
Authorization:Bearer [...]

{
    "sortBy": [
        {
        "direction": "asc",
        "field": "iotSubscription.iotSubscriptionId"
        }
    ],
    "returnFields": ["iotSubscription.iotSubscriptionId", "iotSubscription.subscriptionType", "iotSubscription.domainId"]
}

Combining Sorting, Filtering and Pagination​

It's possible to provide any of the described parameters at the same time. Here's an example that returns a later page of subscriptions updated between 2024-05-18T12:12:34.000Z and 2024-06-30T23:59:59.000Z ordered by the subscriptionId with 5 results per page.

POST https://api.iot.telenor.com/iot-connect/subscription-inventory/v2/search
Content-Type:application/json
Accept:application/json
Authorization:Bearer [...]

{
  "limit": 5,
  "after": "PAGINATION_TOKEN",
  "sortBy": [
    {
      "direction": "asc",
      "field": "iotSubscription.iotSubscriptionId"
    }
  ],
  "filters": [
    {
      "fields": [
          "iotSubscription.lastModifiedAt"
      ],
      "type": "between",
      "values": {
          "min": "2024-05-18T12:12:34.000Z",
          "max": "2024-06-30T23:59:59.000Z"
      }
    }
  ]
}