Throttling

Throttling has been applied to the e-Builder API. Understanding this concept will optimize your use of the API. Throttling refers to the number of API calls allotted within a specified window of time. This is a common practice used among many software companies such as Adobe, Facebook, and Twitter, to name a few. This mechanism is used to prevent the degradation of system performance. By default, 200 API calls are allowed within a 15 minute interval. Each time a call is made to the database, you will receive a message in the response header that includes the total number of calls allowed (X-RATE-LIMIT-LIMIT), the number of calls that remain (X-RATE-LIMIT-REMAINING), and the time at which additional calls can be made (X-RATE-LIMIT-RESET).

oData Response Header

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/atom+xml;charset=utf-8
X-RATE-LIMIT-LIMIT: 15
X-RATE-LIMIT-REMAINING: 11
X-RATE-LIMIT-RESET: 4/16/2014 10:44:20 AM
DataServiceVersion: 2.0;
Set-Cookie: ASP.NET_SessionId=t2prfcfm3c5i5g45urvxhf55; path=/; secure; HttpOnly
X-FRAME-OPTIONS: SAMEORIGIN
Date: Wed, 16 Apr 2014 14:44:04 GMT
Content-Length: 1131228

Although we make this information available, whether or not it displays in its entirety will depend on the tool that is being used. Depending on the tool, there may or may not be settings available that allow you to see all the information available in these alerts.

Sample Throttle Message in Microsoft© Excel© Power Query:

API Throttling Message

The following actions constitute an API call:

  • Refreshing the page
  • Viewing a new e-Builder object
  • Filtering
  • Sorting
  • Depending on the tool, data is initially rendered in a preview window. If the operations listed below are completed within this window and it requires a call to the e-Builder database, it is considered an API call.
  • If you foresee a need to make more than 15 calls within a 15 minute window, please contact e-Builder Support.

It is typical in most API consumer applications to have an action similar to “Apply and Close” which will close the preview window and allow you to manipulate data in their native application, without requiring a call to the e-Builder database. If you've already accessed updated information, use this function to reduce the amount of API calls necessary and remain within the threshold.