API limits
Be aware of API limits when configuring accounts and building apps
Most, if not all, APIs have API limits. These are limits that control how often an external entity, I.E. an API user, can make a call to an application at a defined frequency. There are technological consequences of receiving and responding to API requests. Limits are used to both control costs and help limit possible damage bad actors can inflict on an application. API limits can be by the day, by the minute, by the hour, etc. The bottom line is that if you are making too many API calls you will get errors rejecting API calls that exceed the application's limits.
API calls and the maintenance of APIs cost money. While oftentimes companies won't charge you for using their application's API, sometimes costs are deferred to API users. It's important when setting up an API relationship with a company to understand what costs are associated with using their API. Oftentimes, there are limits to the number of calls that can be made in a day or a month and if you go above this threshold you are charged extra.
At Middle, we want to make sure you are smart about how you use APIs so you don't hit limits and incur unnecessary API charges. This article provides tips on how to maneuver API limits for both account configuration and app development.
What is an API?
API is an acronym for application program interface. An API is the channel or channels in which a computer or computer application can interact with another entity. APIs are made up of endpoints, which are in their most basic form application-specific URLs that can be called to perform actions, such as creating a user, or retrieve data, such as grabbing a users information. Most of Middle's integrations use APIs to connect.
Account API calls
There are a number of ways to control the number of API calls you make at an account level. These are primarily related to which syncs you turn on and how your build your workflows.
Sync controls
Middle has three types of syncs: complete transfers, primary key lookups, and recent record lookups. To recap, below is a breakdown of each type:
Complete transfers - Grab all the data available from an endpoint or external resource. This sync is common for smaller datasets.
Primary key lookups - Request data for a specific record using a primary identifier. For example, if Middle grabs a record, such as an invoice, and sees a user ID associated with that sale, Middle will perform a sync to grab that user's data.
Recent record lookups - Syncs data from a datetime range. For example, grabbing all sales that have occurred in the past hour, every 20 minutes. The datetime scope and frequency of these syncs are configurable from the developer portal.
Complete transfers and recent record lookups are the two most efficient sync types when it comes to getting a lot of data with few API calls. Depending on the amount of data returned, these syncs can equate to a varying number of API calls. That being said, when you want to grab an entire data set or view data over time, complete transfer and recent record lookups are the way to go.
Complete transfers
Since complete transfers are generally used for smaller datasets that don't change a lot over time, when you toggle a complete transfer sync on, this sync will typically run once every 24 hours. Unless you are grabbing a lot of data with a complete transfer, you can assume this sync uses one API call.
Recent record lookups
Recent record lookups are going to run throughout the day and depending on the sync frequency and amount of data each sync runs, you're going to see different numbers of API calls throughout the day. To decrease the number of API calls a recent record lookup performs you can expand the time between syncs via the app's settings.
Primary key lookups
Primary key lookups are the least efficient sync in terms of API calls, but the most efficient in terms of targetting the data you need. When a workflow is dependent on related data you'll want to turn on primary key lookups to maximize workflow reliability. For instance, say you have a workflow that runs every time an invoice is synced by Middle and the workflow's logic references the customer who made the purchase. If you have primary key lookups turned on for the customer data type, Middle will either run every time that customer has not been seen by Middle before or every time we see an invoice associated with that customer (this is dependent on the settings in the app portal). All told, primary key lookups can rack up a lot of API calls. It's important to remain cognizant of this when determining which syncs to toggle on.
When first launching an account it's often a good idea to turn on complete transfers and recent record lookups before primary key lookups, if you are worried about API calls. That way, you have a foundation of data before Middle will run primary key lookups on unseen records. Say if you turned on a sync to grab user check-ins and just the primary key lookup for users, Middle is going to see a pile of check-ins for users it's never seen before and could consequently perform hundreds, if not thousands, of API calls using the primary key lookup. You would likely see a huge spike in API calls as a result and may not like your next API usage bill.
API calls in workflows
Almost every action in a workflow will make one or more API calls. When considering the number of API calls you are making to an application, you must think about how many actions are being used in a workflow. Workflows that are triggered by a large set of data can lead to a lot of API calls if a workflow has a number of actions.
To limit the number of API calls a workflow performs you must be mindful of call volume and how actions are used. Consider if there's a way to limit the number of actions a workflow requires by using the data already synced in Middle, either on the original record itself, using foreign key connections to related data, related data lookups, or record changes. Always filter out as many records as possible using decision nodes before performing an action. If you don't need to perform an API call for the record, branch the workflow so that action is not performed.
Ad-hoc syncs and manual workflow executions
To help you run manual processes, backdate workflows, and troubleshoot, Middle gives you the option to run ad-hoc syncs and manually execute workflows. When performing these it's important to keep in mind the possible API call consequences of these events.
Will the ad-hoc sync lead to lots of API calls?
Will the sync or manual workflow execution lead to a lot of workflows to be run and subsequently a lot of API calls to be performed with the workflow's actions?
Particularly when running ad-hoc syncs, if any related primary key lookups are turned on, you should consider if the data returned by the ad-hoc sync will trigger the primary key lookup to perform a lot of API calls.
Bulk workflow executions
If you have a workflow set up to perform a bulk workflow execution (these are typically found in scheduled workflows), you need to consider how many of the workflows being run will result in actions being performed. If you have a bulk workflow execution set up to run on every user record synced in an app (this could amount to millions of workflow executions) how many of those would you expect to result in an API call? If it's a lot, you will want to think about the API consequences of this.
When building apps
As a developer building or branching off an app in Middle's app portal, you are the architect of an app's function. Consequently, you have a lot of control over an app's API call efficiency and what an app does when it experiences rate limiting. A clear understanding of the app you are integrating to and the use case is important when developing in Middle. Using the use cases for the integration, you should calculate the anticipated API volume your app will drive. When pulling data from an app always favor endpoints that allow you to conduct recent record poll lookups as they allow you to get a bulk of data over time.
Between your app script and first-class tools to limit sync frequency, you have some control over call volume when developing in Middle. The first-class tools live at the app level, meaning that any changes made to the sync will be applied across your Middle instance. When you are being mindful of API calls, changing the frequency of these syncs allows you some control over the number of API calls being performed.
Page size
If possible and stable, you should use the largest page size possible when syncing data from another app. This will likely reduce the number of API calls that are needed to get the data you need.
Bulk primary key lookups
Primary key lookups can lead to a lot of API calls. In cases where an API allows a developer to bulk lookup an array of primary keys in a single API call, you should take advantage of this. With this ability you can see a number of primary keys in related data Middle has synced in and then grab their cooresponding records without a lot of API calls.
API limit errors
When a sync or an action hits an API limit the best course of action is to raise a restart to re-queue the sync or action execution for later. This gives the function other chances to complete successfully and hopefully allows enough time to lapse for the API limit to suffice.
Do not use sleep to address API limits. When you use sleep this runs up AWS (Amazon Web Services) Lambda time which can result in increased load and cost for your Middle instance. Restarts are the most efficient method for instance-wide efficiency.
Recent record lookup frequency
When creating a recent record lookup syncs, you are able to determine how frequently Middle will grab data and how much overlap there will be between syncs. This means that if Middle is syncing every 15 minutes, you can set an overlap of 45 minutes to look at the past hour of data. This helps to pick up anything that was missed on the previous sync.
To limit the number of API calls being made, consider lengthening the amount of time between syncs and decreasing the sync overlap.
Complete transfer frequency
When you toggle on complete transfers they are going to run at the interval defined in the app sync settings in the app portal. Similar to recent record lookups, you can determine how frequently a complete transfer will run. In cases where data is missing that a workflow needs to execute, such as a product's information when performing a workflow on a sale, you can set whether or not the complete transfer should run to find that related record and how much time between sync attempts Middle should wait to try and find that record. While syncing missing related records is important to workflow reliability, toggling off automated related record lookups or increasing the minimum relookup time will cut down on API calls.
Primary key lookup controls
Since primary key lookups have the potential to cause large volumes of API calls, Middle provides a number of controls for this sync type. These controls exist at the record type level in an app and at the sync level.
At the record type level, you can toggle under which conditions foreign key lookups should be performed. This means that when you see a user ID associated with a check-in, for instance, should Middle always perform a sync of that user's information when that user ID is seen or should it only grab that user from the API when they've never been seen before. Options for this behavior include fetching unseen records only, fetching seen and unseen records, and do not fetch records. None of these settings apply if a primary key lookup is toggled off in an app's settings within an account.
Generally, we suggest the "fetch unseen records only" setting. This will limit API calls while ensuring that workflows have the data they need to run. Fetching seen and unseen records is useful when the record type does not have a sync that reliably picks up on changes and a primary key lookup is the only way to ensure data is up to date.
At the sync level, you can control whether a specific primary sync can be used for foreign key lookups. In addition, you are able to control how much time between lookups should elapse before Middle performs another API call. Waiting longer will lead to fewer API calls.
In situations where batch primary key lookups can be performed, there is a setting that allows you to determine the max number of primary keys per call. A higher number without sacrificing sync reliability will be your best bet for API call efficiency.
Last updated
