###Throttled Request Queue
To provide transparent compliance with the throttle limite, Soapi.js includes an [integrated throttled request queue][1].
The queue is integrated into the library and is transparent, requiring no additional coding or consideration.
The current default queue interval is 170ms.
This means that, with the request queue and [request cache][2], you may make requests with impunity and without concern for 503 errors or API abuse and all requests.
Requests that are cached are not subject to queue delays.
The request queue throttle interval can be adjusted from the current default of 170ms via the static `Soapi.RequestQueue` object e.g.
Soapi.RequestQueue.setInterval(intervalInMS);
Care must be taken to self-control bursts so as to comply with throttling rates, otherwise unexpected behavior can, well.. be expected.
As a convenient side effect of implementing a request queue, throttled or otherwise, is the ability to provide feedback when your application is busy requesting data. This capability is implemented via global 'event' handlers and can easily facilitate UI blocking or manipulation e.g. ajax loading mask or other visual cues.
You can find a simple example of this in [StackUsers Lite][3]
/******************************************************
* A cheap auto loading mask by overriding the queue events
* Whenever the queue goes active or complete, wait 100ms
* to make sure the event is not transient and then check
* the queue length and show/hide mask as indicated.
* could use jQuery/BlockUI
*/
Soapi.Events.onQueueActive = Soapi.Events.onQueueComplete = checkMask;
function checkMask()
{
// want a little buffer to eliminate mask flicker
window.setTimeout(function()
{
if (Soapi.RequestQueue.getLength() == 0)
{
unmask();
}
else
{
mask();
};
}, 100);
};
another sample:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>NGINX Throttle Violations</title>
<script src="http://soapi.info/code/js/stable/scripts/Soapi.js" type="text/javascript"></script>
<script type="text/javascript">
var apiKey = 'qgAq_KfDu0KYzlNG-qaTuw';
// default will be set to 170 in next release
Soapi.RequestQueue.setInterval(170); // 30 per 5 sec = 6 per sec = interval 166.6 ms
// see http://stackapps.com/questions/1143/request-throttling-limits
// get a bunch of associations from stackauth
window.setTimeout(function()
{
Soapi.RouteFactory("api.stackoverflow.com", apiKey)
.Users({ pagesize: 100, page: 1 })
.getResponse(function(data)
{
for (var i = 0; i < data.items.length; i++)
{
var id = data.items[i].association_id;
if (id)
{
Soapi.RouteFactory("", apiKey)
.UsersByIdAssociated(id)
.getResponse();
}
};
});
}, 100);
window.setTimeout(function()
{
// get a bunch of tags from meta at the same time - all should be queued and executed with no error
Soapi.RouteFactory("api.meta.stackoverflow.com", apiKey)
.Tags({ pagesize: 1 })
.getPagedResponse();
}, 10);
</script>
</head>
<body>
</body>
</html>
**Next**: [Paged Requests][4]
[1]: http://soapi.info/code/js/stable/docs/symbols/Soapi.RequestQueue.html
[2]: http://stackapps.com/questions/494/soapi-js-fluent-javascript-wrapper-for-the-stackoverflow-api-rc4/1116#1116
[3]: http://stackapps.com/questions/954/stack-users-lite-search-for-users-on-all-stack-exchange-sites-and-view-their-ass
[4]: http://stackapps.com/questions/494/soapi-js-fluent-javascript-wrapper-for-the-stackoverflow-api-rc4/1118#1118