Add documentation for API Throttling

[colinmcglynn]

In a Google Group discussion we realized that both API users and Server Admins could use some more documentation about how API Throttling works in OBA.

The API Keys Section on http://developer.onebusaway.org/modules/onebusaway-application-modules/current/api/where/index.html should include a warning that API keys are rate limited by default to one request per 100ms, but that API users may request changes to their limit from the OBA server administrator.

http://developer.onebusaway.org/modules/onebusaway-application-modules/current/guides/api-webapp-configuration-guide.html The Managing API Keys using the Admin Interface section should mention that the rate limit is configured based on time between calls not calls per time period. (since that has been a point of confusion)
The Creating an API Key in data-sources.xml section should describe how the API limit can be configured here and what the default is if it is left blank.

[barbeau]

This is a larger issue than just documentation for API rate limits, but I thought I'd raise it here too - we have updated documentation on the wikis as well: https://github.com/OneBusAway/onebusaway-application-modules/wiki/API-Webapp-Configuration-Guide

We should figure out a way to merge these.

[colinmcglynn]

@barbeau Oh yeah, I hadn't seen that. The wiki documentation on this is actually really good. I'll second merging chunks of it into the documentation.

[sheldonabrown]

I'll take on this effort. I also want to make clear that's its the hosting organization that gets to ultimately decide the policy on throttling. Although its technically possible to disable throttling altogether, the impact on service side resources and hence hosting costs is enormous.