Conscientious use of the API

Question

What constitutes abuse?

Making an undue number of requests in a short span of time, or regularly exceeding a request quota during "normal" use.

Guidelines for polling

We realize that a great many applications will need to regularly make calls to see if some event has occurred on one of the Trilogy sites.

Examples:

• A user gained/lost reputation
• A question was answered
• New questions - in general, or within a tag or a search query - were posted
• ... and many more

However, polling can incur considerable overhead especially if done too aggressively. So, to lay down some hard guidelines...

If you're application is making identical requests more than once a minute it is probably going to be considered abusive.

Another way to think of it, if you're using more than 15% of your daily request quota simply polling for new activity you're being needlessly aggressive.

What constitutes an "identical" request?

Exactly the same method and query parameters. You don't need to wait a minute before fetching the 2nd page of a request, for example, but you do need to wait a minute between calls to say the /questions method.

Answer 1

Another scenario to consider is testing. Granted tests shouldn't really be hitting the service that hard but I know for my library I have at least 50 integration test that when run all at once would it the /questions method with the same parameters many times in a minute. These requests are done anonymously (with no api key) so I am not sure if you treat those differently.

One thing you didn't cover in your post is what the penalty is for being too aggressive or if any action is taken at all against such apps.

Answer 2

Another good way to be conscientious to the API is think about timing. If your app has certain peaks hours, slow down on the calls after hours (If 75% of users are US, run at 1 call/min from 9-5, and 1 call/5 min the rest of the time)

The same goes vice-versa. If your application isn't completely reliant on up-to-minute data during the day, slow down on the requests during the day and then do your heavy lifting during off-hours. That way it leaves room for applications that are reliant on up-to-minute data. (Statistics Applications, as well as other apps that generalize data come to mind)

As Code Poet pointed out, technically users are using the site 24/7 because the site is fairly global, but realistically speaking, there are definitely off-peak hours. Maybe at some point the devs can share those off-hours with us so we can adjust accordingly to spread out the load.

Answer 3

Obvious, but perhaps worth stating:

• An easy way for desktop apps to reduce API usage is to detect when the screensaver is active or the workstation is locked, and throttle or pause API calls.
• Use separate polling intervals for different types of data: you may need questions every minute, but can live with reputation updates every 5 minutes.
• Favor fewer API calls over smaller payloads when choosing which method to call. E.g., if you want to know the questions tagged foo, bar, and baz in the last minute, retrieve all questions and filter in your application, rather than doing separate calls for each tag.

Answer 4

For a JavaScript library that uses the API to dynamically render content to the end-user of a website, making identical requests often may not be avoidable. With StackUnderflow.js, for example, each user to my blog will make a request to display questions related to the blog entry they are looking at. There's no way to cache that across all users unless I involve the server somehow, and the whole point of the library is to enable people to StackExchange-ify their websites by doing nothing more than including some script (often, the only thing they can do, such as on hosted blog sites).

If I get about 1000 hits to my blog a day, there'd be at least that many requests, many of which will be the same. I don't see a way around that without proxying through some server-side service, which is a very heavy 'ask' for a simple javascript library for only the purpose of reducing duplicate requests (and also makes the library dependent on this proprietary service).

Answer 5

This is a good point. For my application, it does an update of the statistics every day at midnight UTC. I've modified it now so that it does one user every 15 seconds instead of just doing them all as fast as possible. That means for 40 users, it could take up to 10 minutes to update all the days statistics, but that really is not a big deal.

Also, I wouldn't mind running the statistics update at a different time, say to coincide with a "low period" for the server - if such a time exists in such an international site... is there a better time of the day to run statistics updates or does it really not matter that much?