Business Critical Services(BCS) Operational Insights API

API Features

Rate Limiting

Rate limiting is applied per registered application across all API Endpoints. The limit is enforced at 10 requests per second and a maximum of 10.000 requests per day. When the limit is exceeded you will receive a 429 response code back:

http
Copy429 Too Many Requests HTTP/1.1

RateLimit-Limit: 10 
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9854
X-RateLimit-Limit-Second: 10
X-RateLimit-Remaining-Second: 0
Content-Type: application/json; charset=utf-8
Content-Length: 41

{
    "message": "API rate limit exceeded"
}

The body of the response indicates that the API rate limit is exceeded and the headers provide useful information about the rate limiting:

Header Description
Retry-After The time (in seconds) to try again when limit was exceeded
X-RateLimit-Limit-Day The number of API cals allowed per day
X-RateLimit-Remaining-Day The remaining number of allowed API calls today
X-RateLimit-Limit-Second The number of API calls allowed per second
X-RateLimit-Remaining-Second The remaining number of allowed API calls in the current second

Last-Modified and Etag

The response header contains a Last-Modified and Etag header:

http
Copy200 OK HTTP/1.1

Last-Modified: Fri, 11 Feb 2022 03:26:45 GMT
ETag: "542acde734765bba68909bc523388e43"

Last-Modified is the timestamp of the last time data was processed, this is not the same time as the lastUploadTimestamp seen in the collectors endpoint as the data processing and enrichment also takes time.

NOTE: If you have several collectors it will take the timestamp of the last upload across all collectors.

ETag represents the Last-Modified header. This server supports the If-Match or If-None-Match headers. You can query the API regularly for new data and only receive data when new data is available. It lets caches be more efficient and saves bandwidth, as a web server does not need to resend a full response if the content was not changed.

Here is an example where the ETag header value from the previous example is used:

http
CopyGET /inventory/assets HTTP/1.1
Host: api-cx.cisco.com
Authorization: Bearer {{JWT}}
If-None-Match: "542acde734765bba68909bc523388e43"

If the data was modified, a 200 OK response will be returned similar to a regular request with the new data. If the data was not modified, a 304 response code will be returned:

http
Copy304 Not Modified HTTP/1.1

Specific endpoint calling

Where applicable the API endpoints support specific endpoint calling, this is useful when you are interested in one or a couple of items and avoids the need to request all items and filter them client side. When you are interested in the details about the device with deviceId 22345640, you can send the following request:

http
CopyGET /inventory/device/22345640 HTTP/1.1
Host: api-cx.cisco.com
Authorization: Bearer {{JWT}}

This will return information about this specific device:

json
Copy{
  "collectorName": "mycollector",
  "configRegister": "2102",
  "configStatus": "Completed",
  "configTimestamp": "2022-02-02T15:33:37",
  "createdTimestamp": "2022-02-02T15:33:37",
  "deviceId": 22345640,
  "deviceIp": "172.21.1.1",
  "deviceName": "switch",
  "deviceStatus": "ACTIVE",
  "deviceType": "Unmanaged Chassis",
  "featureSetDescription": "",
  "imageName": "",
  "inventoryStatus": "Completed",
  "inventoryTimestamp": "2022-02-02T15:33:37",
  "ipAddress": "172.16.1.1",
  "isInSeedFile": true,
  "lastResetTimestamp": "2022-02-02T15:33:37",
  "productFamily": "Cisco Catalyst 3560-E Series Switches",
  "productId": "WS-C3560X-24P-E",
  "productType": "Metro Ethernet Switches",
  "resetReason": "",
  "snmpSysContact": "",
  "snmpSysDescription": "",
  "snmpSysLocation": "",
  "snmpSysName": "",
  "snmpSysObjectId": "",
  "softwareType": "IOS",
  "softwareVersion": "15.1(4)M4",
  "userField1": "",
  "userField2": "",
  "userField3": "",
  "userField4": ""
}

NOTE: This returns the item itself and not a list of items as in the /inventory/device endpoint.

Filtering

Some API endpoints supports filtering, this is useful when you are interested in items that match a specific conditions. To request only the field notices where the value of matchConfidence is equal to Vulnerable, the below request can be used:

http
CopyGET /productAlerts/fieldNotices?matchConfidence=Vulnerable HTTP/1.1
Host: api-cx.cisco.com
Authorization: Bearer {{JWT}}

The response will only contain items for which the matchConfidence is equal to Vulnerable:

json
Copy{
  "items": [
    {
      "deviceId": 15492283,
      "fieldNoticeId": 28655,
      "matchConfidence": "Vulnerable",
      "matchConfidenceReason": "Match on PID",
      "physicalAssetId": 174051238
    },
    {
      "deviceId": 26592438,
      "fieldNoticeId": "62814",
      "matchConfidence": "Vulnerable",
      "matchConfidenceReason": "Match on PID, TAN, Serial Number",
      "physicalAssetId": 429970563
    },
    ...
  ]
}

NOTE: Not every API endpoint supports filtering and filtering is only possible on some attributes, this is documented in the OpenAPI Specification.

Field Masks

It is possible to specify the attributes of interest so only those are provided in the response. This is supported on all attributes on all endpoints by using the url parameter fields. If you are only interested in the deviceId, deviceStatus and productId for example you can send the following request:

http
CopyGET /inventory/device?fields=deviceId,deviceStatus,productId HTTP/1.1
Host: api-cx.cisco.com
Authorization: Bearer {{JWT}}

The response will only contain the requested attributes:

json
Copy{
  "items": [
    {
      "deviceId": 15414373,
      "deviceStatus": "ACTIVE",
      "productId": "ISR4321/K9"
    },
    {
      "deviceId": 15414374,
      "deviceStatus": "ACTIVE",
      "productId": "ISR4321/K9"
    },
    ...
  ]
}

NOTE: This can be used in combination with specific endpoint calling or filtering.

Next