To compensate for 503 errors and provide a capable, albeit a bit slower, client library fortransparent compliance with the APIthrottle limite, Soapi.js currently includes includes an integrated throttled request queue.
The current default queue interval is 300ms for all api endpoints other than api.stackoverflow.com, which does not demonstrate out-of-band throttling problems170ms.
This means that, with the request queue and request cache, you may make requests with impunity and without concern for 503 errors or API abuse and all requests, except those to api.stackoverflow.com, will be transparently queued up and executed at an acceptable rate.
The request queue throttle interval can be adjusted from the current default of 300ms170ms via the static Soapi.RequestQueue object e.g.
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.
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
The outstanding throttle issues, 1, 2, 3, 4, are currently under review and upon resolution the default queue interval will be reduced to nil providing much more responsive api access while maintaining error free execution.
