Understanding Pagination

The Cisco PSIRT openVuln API supports pagination for endpoints that are expected to return more than a single object/page. Paginated GET endpoints only return a subset of the results in the first response. The following query arguments are used to shape paginated results:

• pageIndex
• pageSize

The pageIndex field is an integer representing the current page index out of total number of pages (TNP).

  Total advisories / pageSize = TNP
  (1000 / 100 = 10)

Example using Pagination

This examples shows requesting all advisories in the year 2023 using pagination.

Request

curl -X GET -H "Accept: application/json" -H "Authorization: Bearer <removed>" 'https://apix.cisco.com/security/advisories/v2/year/2023?pageIndex=1&pageSize=10'

Response

The response will contain paging information.

    "paging": {
        "next": "/year/2023?pageIndex=2&pageSize=10",
        "prev": "NA",
        "count": 79
    }

Sorting Results

Sorting is not supported in the Cisco PSIRT openVuln API. Client side code can be used to achieve this result.

Filtering Results

Filtering is defined by the end point. For example you can pull information back based on time period, product, software etc as outlined in the guides section.

Rate Limits on Results

Transaction quotas are applied to the openVuln API to ensure ideal performance for all users and to prevent abuse.

Per Application

The following default rate limits are applied per application.

• 5 calls per second
• 30 calls per minute
• 5000 calls per day

Response Code

The following response code is used to indicate if a rate limit has been exceeded:

• A 429 status code will be returned when the rate limit has been exceeded. With a body indicating the error.

When an application exceeds the rate limit, the following message will be returned in the response body:

X-Mashery-Message-ID: 020a7572-1faf-4121-bd82-a599626f1251
X-Error-Detail-Header: Account Over Rate Limit
X-Mashery-Error-Code: ERR_403_DEVELOPER_OVER_RATE
Content-Type: text/xml
Date: Tue, 16 May 2023 05:30:51 GMT
Content-Length: 93
The API key you are using has attempted to access the API more than the rate limit of 30/min.

Common Causes

Rate limiting can occur for a variety of reasons, but some of the common causes are the following:

• Running high-volume API monitoring tasks in realtime can overthrottle the system and lead to 429 errors
• Scripts that run with little to no maintenance can degrade the performance of your organization's API requests and use up quota
• Not using a local cached copy of data; once original data is collected

Recommendations

Cisco PSIRT posted recommendations on Cisco PSIRT OpenVuln API rate-limiting on the community support page.

IF we introduce 429 with retry-header:

If the defined rate limit is exceeded, the Cisco PSIRT OpenVuln API will reply 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 has been exceeded. You may have to wait potentially longer if a large number of requests were made within this timeframe.

A simple example which minimizes rate limit errors:

response = 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