Edge Intelligence API

Pagination

List/Get API support the "page" and "size" query parameters for pagination.

  • page — This specifies the page number.
  • size — This specifies the page size.
    The page and size are optional parameters. The default values for page and size are 1 and 10, respectively.

NOTE: For the List/Get API, 200 is the largest page size that is acceptable and specified in the API specification.

List/Get API provide the pageinfo JSON object as part of the response with the following data:

  • totalCount — total number of elements found for the given query/filtering criteria
  • page — current page number
  • size — page size
  • count — number of elements in current page

Filtering

List/Get API support the "filter" query parameter for filtering.

You can provide the following query parameters to filter the response for each API:

AGENTS:

  • search: You can search for data using any string that is part of the EI Agent Name, Network Device Serial Number, Network Device Model, EI Agent Version, Number of Mapped Assets to the Agent, EI Agent Status, and Data Pipeline Status.
  • label: Search data using the EI Agent Name.
  • hardwareSerial: Search data using the Network Device Serial number of EI Agent.
  • hardwareModel: Search data using the Network device model of EI Agent.
  • brokerVersion: Search data using the EI Agent version.
  • numOfMappedAssets: Search data using Number of mapped Assets to the agent.
  • connectionState: Search data using the EI Agent Connection Status.
  • dataPipelinesStatus: Search data using Data Pipelines status.
  • The main search filter is case insensitive, whereas the other field-specific search filters are case-sensitive.

ASSET Types:

  • search: You can search for data using any string that is part of asset type name and connection type.
  • name: Search data using the Asset Type name.
  • connectionType: Search using the Connection Type.
  • The main search filter is case insensitive, whereas the other field-specific search filters are case-sensitive.

Sorting

List/Get API support the orderBy query parameter for sorting. The desc query parameter is used to indicate the desired sort order of a column/attribute. It is a Boolean query parameter with a default value of false.

For example: * orderBy=label * orderBy=label, desc = true

When the orderBy parameter is not provided, the default sorting used is orderBy=label and desc=true.

You can provide the following field names (The fields present in the response) for the "orderBy" query parameter.

AGENTS:

  • brokerVersion
  • connectionState
  • creationTime
  • dataPipelinesStatus
  • hardwareModel
  • hardwareSerial
  • id
  • label
  • numOfMappedAssets
  • offlineTime
  • startTime

ASSET Types:

If the "orderBy" parameter is not provided, the default sorting applied is "orderBy=name" with "desc=true."

  • name
  • connectionType
  • id
  • Configuration fields

Rate Limit

Per Organization

  • The Edge Intelligence API is limited to 5 requests per second, per organization.
  • A concurrency limit of 5 concurrent requests per IP is enforced.

Response Codes

  • A 429 status code returns when the rate limit is exceeded, with the Retry-After header.
  • When an application exceeds the rate limit, the following message returns in the response body:
Code Snippet
Copy{
  "errors": ["Too Many Requests"] 
}

Common Causes

Rate limiting can occur for a variety of reasons. Some of the common causes are the following:

  • Running high-volume API monitoring tasks in realtime can over throttle the system and lead to the 429 errors.
  • Scripts that run with little to no maintenance can degrade the performance of your organization's API requests and use up the quota.

Tips to avoid being Rate Limited

Utilize the Retry-After header and backoff to minimize compounded rate limit issues. Ensure that if the limit is exceeded, an appropriate action is being taken to handle the 429 responses.

Handling Limiting Gracefully

If the defined rate limit is exceeded, the Edge Intelligence API replies with the 429 (rate limit exceeded) error code. This response will also return a Retry-After header, indicating how long the client should wait before making a follow-up request.

  • The Retry-After key contains the number of seconds the client should wait.
  • Expect to backoff for 1 - 2 seconds if the limit is exceeded. You may have to wait longer if a large number of requests were made within this timeframe. A simple example which minimizes rate limit errors:
Code Snippet
Copyresponse = requests.request("GET", url, headers=headers)
if response.status_code == 200:
    # Success logic
elif response.status_code == 429:
    time.sleep(int(response.headers["Retry-After"]))
else:
    # Handle other response codes
Next