This guide provides details on querying and understanding responses from Auvik’s APIs and provides Auvik API development best practices to help improve your experience.
We’ll cover the following topics:
- API URL
- Debugging with cURL verbose mode
- Authentication
- Rate limits
- Non-standard responses, such as a response for a query with no results and responses with errors
- How to improve performance when making API calls
- General guidance on statistics API requests
API URL
The cURL (client URL) example in the API reference is set up so that only the cluster region needs to be updated—there’s no need to change auvikapi to match the account’s domain prefix. The cURL calls the Auvik service, which makes the calls based on your Auvik credentials and API key.
You’ll need to update the “region” in the API URL to match the region in which your account resides. For example, in https://auvikapi.us1.my.auvik.com, us1 is the region. To see your region, log into your Auvik dashboard and look at the URL in your browser’s address bar.
If you specify the incorrect region or the account is moved to another region, it will trigger an HTTP 308 Permanent Redirect code. Make sure your app is checking for a 308 code, and if the code is received, it’s updating the region for the account.
Debugging with cURL verbose mode
When calling the APIs in cURL, you can run them in either silent mode or verbose mode. Silent mode completes the API call but doesn’t show any messages about possible failures. Verbose mode calls the API and also returns details useful for debugging, such as response headers.
To run cURL in verbose mode, add “-v” into the cURL commands ahead of the URL. This will show you all responses received, including any of the API success or error codes you might encounter.
Authentication
Auvik APIs use basic authentication when the username matches the account username, and the password is the API key. Basic authentication must be used in conjunction with an HTTPS connection for security. Auvik supports TLS (Transport Layer Security) versions 1.2 or higher.
Confirm that your application supports the minimum Auvik security requirements. For example, if you’re using a .NET framework to call the Auvik APIs, we recommend you set the following:
[Net.ServicePointManager]::SecurityProtocol =
[Net.SecurityProtocolType]::Tls12
To generate an API key, see How to generate an API key.
To use the Auvik APIs, users must be authorized to access the client. Users must also have the correct role permissions for each API they’d like to run.
Rate limits
Auvik APIs have a rate limit of 2500 requests in a 5 minute period.
Response for a query with no results
If a query has no results, a 200 code is returned with an empty result.
How to handle API errors
Auvik APIs return two pieces of information when an error is encountered:
- An HTTP error code
- An array of error objects in the HTTP response
Applications that integrate with Auvik using APIs should handle errors as indicated below. This can improve the overall experience for your users.
400 bad request
This indicates the API request contains errors such as an invalid filter or filter value in the query parameters. The response body indicates what part of the request is invalid.
Please don’t automatically retry this request. First, check the API request in your application. See Auvik API Reference.
401 not authorized
This indicates the username or the API key is invalid for the given client.
Please don’t automatically retry this request. First, confirm with the Auvik administrator that the client domain, username, and API key are valid.
403 forbidden
This indicates the user doesn’t have permission to call the API for this client, or the user isn’t authorized to access the client.
Please don’t automatically retry this request. First, confirm with the Auvik administrator that the API user has the appropriate role permissions and authorization to access each client contained in the request.
404 not found
This indicates the URL or the entity IDs provided in the path parameters are invalid.
Please don’t automatically retry this request. First, confirm that the URL is valid. If it is, verify that the entity IDs in the path parameters are valid.
500 something went wrong
This indicates a potential issue within the Auvik system.
Please use an exponential backoff and retry. If the issue persists, contact Auvik support.
How to improve performance when making API calls
Below are some best practices that may help improve the performance of your application and the experience for your users.
Verify credentials before making API calls
Use the Verify Credentials API to confirm your credentials are correct before making a call to an endpoint. This helps detect issues earlier and can make for a better user experience.
Filter query to desired data set
Auvik APIs contain filters to help you reduce the data set closer to what you may need. This helps query performance as it reduces the amount of data that needs to be transferred, and the amount of processing that you need to do in your application. For example, if you only need critical alerts created after a specific date and that haven’t been dismissed, you can use
filter[severity], filter[dismissed], and filter[detectedTimeAfter].
Cache data that doesn’t frequently change
The number of API calls can be reduced by caching data that doesn’t frequently change. This can improve the performance of your application because it doesn’t need to wait for the API call to complete. Most Auvik APIs have a filter— filter[modifiedAfter] —to return entities that have changed since a given date. This reduces the size of the data that’s returned and your application has to process.
General guidance on statistics API requests
There are many timeouts between your application and Auvik servers that can limit how long an API request takes. The more data you receive from an API response, the more likely you are to encounter a timeout.
Here are a few parameters you can use to control data size and avoid timeouts:
- Number of tenants - Split large lists of tenants over multiple calls
- Page size - Reduce the page size
- Timeframe and granularity - Decrease the timeframe for granular data points