Fantasy Platform API Rules - CBSSports.com Development Center

CBSSports.com Fantasy Platform API Rules

The overall goal of Fantasy Platform API Rules is to ensure that the CBSSports.com fantasy user experience is a good as possible, and not affected by server unresponsiveness caused by too much load on the system. While our environment is built to minimize the impact that a rogue league or application can have, we do need your cooperation.

We realize that different applications will need different levels of access and will also require to have a wide range of API call volume. An application that's installed by 25,000 users of course is going to put a heavier burden on our servers than one that has 1,000 users. As a result, setting absolute limits or thresholds is not an optimal solution.

The vast majority of the API calls are really fast and do not put much of strain on the system. Nonetheless, making unnecessary calls needs to be avoided. But there are a few that can be easily abused and cause problems. Please be advised that we will be monitoring API usage and if we determine that an application has caused a system overload, or is in imminent danger of doing so, we will turn off all instances of the application and will keep it that way until the developer is able to provide a version that solves this problem.

In order to reduce the possibility that your application will pose issues for the Fantasy Platform, please adhere to the following:

Don't look for refreshed data too frequently. Some API calls return data that updates in real time. You may be tempted to update this data every 30 or even 20 seconds. Most of this will be wasteful, since in most cases, our data will not be updating and propagating through the environment that fast. In general, you should'nt make the same call more frequently than once a minute.
Cache data whenever possible. Some data doesn't change that often. It's ok for your application to save it on your servers when it makes sense. This will speed up the performance of your application and reduce the load not just on our servers but also yours. For instance, if you are creating a draft room application, you don't have to get the team names on every update. You can get them once, save them locally and assume that they won't change for the duration of the draft.
However, do not cache data for too long. In most cases you should not cache the data for longer than a day. Eventually our API's should provide caching information and ways to validate cached data, but we are not there yet. In the meantime, keep the caching intervals short enough.
Do not send in any update data that came from a cached call. If you are building a 'Offer Trade' type page, for example, that requires data to be changed, make sure that you are using the latest data. In that case, when getting the initial rosters from which you want the user to choose the players to be involved in the trade, make sure that the data is the latest.
Saving data in your local servers for caching purposes is allowed, but note that under the Terms of Service you can not use that data to power other products or gather aggregated data or other intelligence about our users.
Don't attempt a retry too soon, and give up quickly if the server doesn't respond. While we will do our best to keep the API servers up and running at all times, problems do occur. Every once in a while, one of the API calls you make may not return quickly and you may be tempted to try again. You should wait at least 30 seconds before attempting a retry. And you shouldn't retry more than 3 times. If there is something wrong with our servers, retries will only make matters worse. After the third failure, it's ok to display an error to the user indicating that they should try later on.
Do not retry operations that change data. The operation may have gone through and the return message was just lost. Attempting a retry on that may result in corrupted data. If your update didn't return in a timely manner, it's ok to give an error to the user if you can't verify that it was completed. The user will then determine whether the operation worked and may attempt to retry the operation.
Sort API results data. The API's will tend to return data in an unsorted list. In most cases you will need to properly sort this data before presenting it to the user. This applies to things such as rosters, teams, positions used, etc.
Use the Get Roster for an all teams call instead of calling the Get Roster for each team individually. If you need to get the rosters for all teams (say to build a roster grid type view), you should call the Get Rosters API without a team id which will return all teams, as opposed to calling it once for each team. This also applies to the API's for Schedule and Transaction Log.
Do not load test the API service. You will likely want to make sure that your infrastructure can support the audience you are expecting. To prepare for it, as well as for tuning performance, you may want to load test it. A common way to do a load test is to make many simultaneous calls to your application, which will in turn make a lot of API calls to our servers. We suggest you load test by replacing the Fantasy Platform API calls with short sleep intervals to simulate the server waiting for a response. If you feel confident that it is important to load test your application end-to-end, including the API calls, please do these tests during off-hours (2am-6am ET).