Overview
This article contains the Quantive best practices for using the API. It is primarily directed at using the API within insights, but the principles apply to any API usage.
Authentication and Security
When calling Quantive's API via the Angular http module from an insight, the required headers for the account ID and API token will be automatically injected for the user viewing the page, so your code should not need to handle these
The Angular http module should be favored when calling Quantive from insights API for this reason
API tokens or keys should be treated like passwords and should never be hard coded in JavaScript
Favor using session tokens instead of permanent tokens whenever possible
In JavaScript, you can retrieve the session token and account ID for the logged in user using this code:
const ACCOUNT_ID = JSON.parse(localStorage.getItem("accountId"));
const API_TOKEN = JSON.parse(localStorage.getItem("token"));
If asking the user for an API token or key as part of an input, use a password type input field
General Best Practices
Review the API documentation
US Data Center (.us is in your URL): https://developer.us.gtmhub.com/
EU Data Center: https://developer.gtmhub.com/
All API calls in code should have success and fail handlers or at a minimum a comment indicating why there is not a success or fail handler
In JavaScript, do not use blocking/synchronous calls. Use a success handler instead
In JavaScript, do not use Angular's http module to make API calls outside of the Quantive account
The Account ID and API token are automatically injected as headers into calls made using the Angular http module, so making calls to a 3rd party API could expose the account ID and token to that 3rd party API
If you’re not sure how to do something, check in the browser console’s network tab to see how the call is made by the Quantive application when completing an action in the user interface
Do not allow users to make API calls to things they don’t have access to do - I.E. allow a non-admin user to see a delete button that deletes a user
The call will fail, but in general they shouldn't be able to make the call in the first place
GET Calls
When using Angular, you can use $http.get() or $http()
When using jQuery, use $.get unless you need to apply custom headers or otherwise use special ajax options, in which case you should use $.ajax instead
When making a GET call that supports the ?fields query parameter, use it to limit to the fields you’re interested in, even if the list is long
❌Avoid This:
https://app.us.gtmhub.com/api/v2/metrics✔️Do This:
https://app.us.gtmhub.com/api/v2/metrics?fields=id,name,sessionId,goalName,goalIdThe change in this example reduces the size of the returned data payload by ~98%
Calls that Modify Data (POST/PATCH/PUT/DELETE)
When using Angular, you can use shortcut methods like $http.post() or the $http() method
When using jQuery, always use $.ajax (not all verbs have jQuery shortcuts)
Use PATCH instead of PUT whenever possible to avoid changing things you don’t intend to change
Some endpoints do not support a PATCH and only support PUT
When using a PATCH call, only supply the properties that you intend to modify
When using a call that modifies data for the first time, test it on an object you don't care about before using it on "real" objects
Always verify that the behavior in the UI is correct after making the call
In some cases, the API does not enforce that values that are enforced in the UI, which can lead to unexpected results in the UI
Be very careful with DELETE calls in particular to only delete what you intend
Multiple Simultaneous Calls
Quantive's API can handle multiple simultaneous calls, but keep it within reason. Don’t make 100+ calls at the same time.
With calls that modify data in particular, it may make sense to sequence the calls to prevent them from all being made at once
You must do this if you are touching the same object multiple time or need one call to complete before another (I.E. creating a parent objective then creating a child objective)
To sequence calls, initiate the second call in the success handler for the first call
Paged GET Calls
Many GET calls will return paged results (I.E. a maximum of 100 results per API call or “page”)
When responses are paged, use the take and skip query parameters to indicate which page you want
The “take” value indicates how many results per page. For Quantive, the maximum is usually 1000 and the default is usually 100.
“limit” can also be used on some calls
The “skip” value indicates how many results to skip
Call | Returns |
| Metrics 1-200 |
| Metrics 201-400 |
| Metrics 401-600 |
In Quantive, all paged calls will always return the “totalCount” property which you can use in code to determine how many pages you need to get all results
GET calls for paged data should be sequenced - the page limits are in place for performance reasons, running all paged calls simultaneously defeats the purpose