All Collections
Best Practices: Using the API
Best Practices: Using the API

Quantive best practices for using the Rest API

Boyan Barnev avatar
Written by Boyan Barnev
Updated over a week ago


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

  • 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:

    • ✔️Do This:,name,sessionId,goalName,goalId

    • The 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 $ 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



Metrics 1-200,name&take=200&skip=200

Metrics 201-400,name&take=200&skip=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

See Also

Did this answer your question?