Authentication Error Limits
After 40 failed authentication attempts from the same IP address in less than 2 min, the soure requestor IP address will be blocked for 2 hours. All requests to authentication endpoints will be blocked.
TrackTik Customer Support and DevOps can be contacted to have the IP ban lifted sooner than the 2 hour window.
Default Number of Items Returned
By default, if no requested number of result items is requested with a filter parameter, 100 items will be returned.
Maximum Number of Returned ItemsThe maximum number of returned items is 1000, and you can request up to it using the limit filter:
[GET] /zone-clients?limit=1000
"meta": {
"count": 3357,
"request": [
"zone-clients"
],
"itemCount": 1000,
"security": {
"granted": true,
"requested": "admin:zone-clients:view",
"grantedBy": "admin:*",
"scope": null
},
"debug": null,
"resource": "zone-clients",
"limit": 1000,
"offset": 0
}Notice how there are 3357 possible items to return (count value), but that with the limit=1000, and looking at the itemCount value, only 1000 of the 3357 are returned.
Sorting Items in a Response
When you make a basic GET call to one of TrackTik's API endpoints, it will in general return a list of records sorted by their main index (id) numbers. This means that the oldest information is returned first.
That might not be useful in all situations especially when a person is looking for the new data, or needs to sort by name alphabetically, and so on.
To sort the items of a response to an API call, you need to use the "sort" parameter. It sorts in ASCENDING order by default, and you can prefix the value to the parameter with a "-" to reverse it to DESCENDING.
E.g.
Say you want to see the latest list of new employees. You would have a DESCENDING sort on the id index values as they would occur in the database, so you would:
[GET] /rest/v1/employees?sort=-id
Notice the "-" before the "id" to switch the ASC sort order to DESC.
You can also do this on employee names for examples. So for a list of employees by alphabetical names, you would request:
[GET] /rest/v1/employees?sort=name
The sorting feature does not currently support multiple dimensions.
Paginating Items Returned (offset)If you want to see a different subset of the possible items that can be returned, you can use the offset filter to request “the next interval of items as defined by the limit value in the API request”.
Let’s say you’re looking at a sorted list of employees in groups of 5 (for performance, or some tool with a GUI). You would request the first 5 with:
[GET] /employees?limit=5&fields=id,name,email&sort=id
{
"id": 1000,
"name": "TrackTIk Support (HQ)",
"email": "E@E.com"
},
{
"id": 1001,
"name": "TrackTik Support (NE)",
"email": ""
},
{
"id": 1002,
"name": "TrackTik Support (NW)",
"email": ""
},
{
"id": 1003,
"name": "TrackTik Support (SE)",
"email": ""
},
{
"id": 1004,
"name": "TrackTik Support (SW)",
"email": ""
}Now let’s add an offset to get the next 5, not including the previous items already returned:
{
"id": 1005,
"name": "Joan Slater",
"email": ""
},
{
"id": 1006,
"name": "John Mills",
"email": "BMills@prioritysecurity.com"
},
{
"id": 1007,
"name": "Jake Bond",
"email": "JBond@prioritysecurity.com"
},
{
"id": 1008,
"name": "Molly Sutherland",
"email": "MSutherland@prioritysecurity.com"
},
{
"id": 1009,
"name": "Mike Brown",
"email": "mbrown@prioritysecurity.com"
}
Quick Summary
You already know about limits:
[GET] /employees?limit=5&fields=id,name,email&sort=id
A request like that will get the first 5 records stored in the database (because of the primary key sorting of sort=id parameter)
But to get the next 5 after that, you can use an offset value. The offset value is the number of rows to skip over before beginning the count up to the limit. So if the previous call returned the first 5, to get the next 5 after that would be:
[GET] /employees?limit=5&fields=id,name,email&sort=id&offset=5
And for the next 5 after the first 10:
[GET] /employees?limit=5&fields=id,name,email&sort=id&offset=10
When developing a call loop to essentially paginate like this, you would set the limit variable to 5, and the offset to the limit variable times the number of pages to skip ahead to.
First (no pages) 5: limit 5, offset 0 (offset = 5 x 0)
Second 5 (page 1): limit 5, offset 5 (offset = 5 x 1)
Third 5 (page 2): limit 5, offset 10 (offset = 5 x 2)
Performance is More Often About Record Counts in the Database
In day to day integrations with customers, we’ve noticed that even if you filter and offset, when there is an endpoint that requires at least one search filter, like the reportDateTime value of reports accessible via /reports, the back-end data retrieval process still has to crawl through the entire recordset finding matches with the required filter.
This means that if a customer database has 17 million reports, that any little request to /reports in that dataset is going to take several minutes. This can be improved by looking for ranges of primary keys instead of indexed fields, but it will still take a while.
When working with large data sets, it’s important to manage expectations. Filters can only do so much.
API Gateway Limits
An API call must not exceed 30 seconds before a response is generated or it will timeout with a 504 Gateway Timeout HTTP Status Code. Limits and offsets are not as effective at improve large API call response times compared to filters on ranges of dates and indexes, so strategize accordingly.
API limits (requests per second) are not currently tiered, but they will be in the future and we're planning on offering a dashboard to monitor your own activity as part of the implementation. For now the Firewall is enforcing limits more generally for everyone.
URL Max Length
Any API call mustn't be more than 10,240 characters in length. Making API calls that exceed this will return an error with HTTP status 414 URI Too Long.
If the request header is too large, an error will be returned with HTTP status of 494.
API Request Frequency Limits
You should try to not exceed ~4000 requests per 5 minutes. Once the limit is exceed, a throttling will occur and relaxed again after the next 5 minutes. You'll receive an HTTP status of 429 Too Many Requests if you exceed the limit.