API Best Practices

This article covers API Rate Limits, API Usage Tips, Caching, Prioritizing Active Users, and Error Handling.

API Rate Limits

Check your plan details for the specific rate limit. Rate limits are applied globally for an account and linked to the API keys provided for each application in the Appreciation Engine Dashboard. An application may have multiple partner keys, and each key contributes to the overall API rate.

Example: Developer A and Developer B in two different locations make calls using the same application API keys. The requests will both contribute to API use under the application limits.

Example: Developer A and Developer B in two different locations make calls using different partner keys for the application. The requests will both contribute to API use under the application limits.

Rate Limits can be enforced as soft or hard caps.

Soft caps do allow burst traffic that may exceed the allocated rate limit but will impact overall service performance if these limits are exceeded often. Hard caps will stop API traffic once the allocated limit is exceeded but ensure more stable overall performance. Soft caps are only available to Enterprise customers.

API Usage Tips

The tips below are there to help you optimize code and reduce the possibility of exceeding account limits for API usage:

• Do not make burst of calls, spread out the calls throughout the day.
• Do smart fetching of data (important data, non duplicated data, etc.).
• Specify upper and lower ranges on the values you are querying against. (e.g. lastUpdated or id values)
• Avoid large offsets when paging, especially when retrieving large data sets
• Adjust ranges to keep offset reasonable.
• Rather than paging to 10K+ pages based on a starting date, adjust the start date forward in time as you make additional calls.
• Most endpoints enforce a maximum offset value of 100K
• Default date range if none specified is 1 week. The maximum date range - even if a bigger range is specified - is 6 months.
• Use the fields parameter to limit fields returns for each member, and thus the size of data returned.

Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the API on every page load of your website landing page. Instead, call the API at regular intervals and load the response into a local cache. When users hit your website load the cached version of the results.

Prioritize Active Users

If your site keeps track of many users (for example, fetching their current status or statistics), consider only requesting data for users who have recently signed into your site.

Error Handling

If there is an error in the API request made then an error response code is returned. Developers should try to check and catch any non-expected responses and handle appropriately.

Error Response Structure:

{
    "error": {
        "code": 48,
        "message": "invalid member"
    }
}