Overview

This article contains the Gtmhub 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

  • 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

  • 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 Gtmhub 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 making a GET call in JavaScript, you can 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,goalId

    • The change in this example reduces the size of the returned data payload by ~98%

Calls that Modify Data (POST/PATCH/PUT/DELETE)

  • Always use $.ajax in JavaScript for these kinds of calls

  • 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

  • Gtmhub’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 Gtmhub, 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

https://app.us.gtmhub.com/api/v2/metrics?fields=id,name&take=200&skip=0

Metrics 1-200

https://app.us.gtmhub.com/api/v2/metrics?fields=id,name&take=200&skip=200

Metrics 201-400

https://app.us.gtmhub.com/api/v2/metrics?fields=id,name&take=200&skip=400

Metrics 401-600

  • In Gtmhub, 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

Code Best Practices: Insight JavaScript

Gtmhub API: Quickstart

API Methods Overview

Did this answer your question?