This guide provides details on querying and interpreting responses from Auvik’s APIs, and provides insight into best practices for development with Auvik APIs.
We’ll cover the following topics:
- API URL
- Debugging with cURL verbose mode
- 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
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.
Accordingly, you 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 gets 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, updating the region for the account.
Debugging with cURL verbose mode
When calling the APIs in cURL, you can run them in 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 other 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.
Auvik APIs use basic authentication where the username is 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) version 1.2 or higher. You should check that your application supports the minimum required by Auvik. For example, if you’re using a .NET framework to call the Auvik APIs, we recommend you set the following:
To generate an API key, see How to generate an API key.
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 Auvik APIs should handle errors as indicated below. This can help the overall experience for your users.
400 bad request
This indicates the API request contains errors (for example, 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. 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. Confirm with the user that set up the integration in your application that the client domain, username, and API key are valid.
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. Confirm with the user that set up the integration in your application 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. Check 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 techniques to 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 verify 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 to a smaller set closer to what you 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
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 that your application has to process.