The Fantasy Platform uses a RESTful API that allows you to build applications that provide an enhanced customer experience for owners of CBSI Fantasy Sports leagues. Your Fantasy Platform application will reside in an iframe on the CBSI Fantasy Sports site. Your application will have extensive access to the the CBSI fantasy sports system and data to enable you to tailor a custom gaming experience for owners who purchase your application.

A RESTful API

The Fantasy Platform uses a REST API. This means that the API consists of a set of resources which you can request or manipulate using the standard HTTP methods GET, PUT, POST, and DELETE. Each resource has a unique URL. You request the resource by doing and HTTP GET on the resource URL. For some types of resources, you can create new resources using PUT or POST, edit existing resources using POST, or delete resources using DELETE.

It is important to understand that, in accordance with the principles of REST, all actions in the Fantasy Platform API consist of GETting, PUTting, POSTing, or DELETEing specific data resources. There are no other verbs or actions in the Fantasy Platform API. Everything is done by manipulating resources using standard HTTP methods. Similarly, the success or failure of all operations is reported using standard HTTP status codes.

Some resources have sub-resources which you can request by adding appropriate parameters to the resource URL. For example, you can request the Player Ranking resource using this URL:

http://api.cbssports.com/fantasy/players/rankings

This URL will return the rankings for all players. If you want to get the rankings for just the players who play a particular position, you can select the rankings for a particular position like this:

http://api.cbssports.com/fantasy/players/rankings?pos=RF

Every resource returned by the Fantasy Platform is specific to the currently logged in user. Every request to the Fantasy Platform includes an access token that encodes the name of the logged in user, their fantasy league, and the sport of the fantasy league. Thus every resource returned by the Fantasy Platform is filtered (where applicable) for the user, the league, and the sport.

Resources

The resources available through the Fantasy Platform cover the following areas:

Professional players

Players List - A list of all pro players. This list includes the id for every player, which you can use to request resources specific to an individual player. You can also specify search terms to narrow the list of players returned.

Player Outlook - The outlook for a player for the coming fantasy sports season.

Player Update - News items about a particular player.

Player Rankings - The current rankings for all players, or players at a particular position.

Draft Results, Average Draft Position, Most Activated, Most Added, Most Benched, Most Dropped, Most Traded, Most Viewed - Statistics on how professional players are being used by owners in a fantasy league.

Stats - A list of statistics for a player or players.

News

Fantasy Headlines - A list of the headlines of Fantasy News stories provided by CBS Interactive. The list include the ID of each story, which you can use to request the Fantasy Story resource.

Fantasy Story - A new story provided by CBS Interactive.

League Headlines - A list of the headlines of League News stories provided by members of a fantasy league. The list include the ID of each story, which you can use to request the League Story resource.

League Story - A new story provided by a member of a fantasy league.

Fantasy leagues

Fantasy Owners - A list of owners in a fantasy league.

Fantasy Teams - A list of teams in a fantasy league.

Rosters - The rosters of the teams in a fantasy league.

Schedule - The schedule for matchups in a fantasy league.

Breakdown Standings, By-Period Standings, Overall Standings, Power Standings - the standings of a fantasy team in a league according to various criteria.

Transactions

Trades - A list of trades in a fantasy league.

Trade - A fantasy trade. Trades may be in various states, depending on the trade rules used by the league. Your application can create a trade offer, vote on, accept, or reject a trade on behalf of the logged-in user.

Transaction Log - A log of transactions in a fantasy league.

Lineup Changes - Your application can make lineup changes on behalf of the logged-in user.

Waiver Order - A list of fantasy teams and their waiver rank.

Message boards

Message List - A list of messages on the message board of a fantasy league.

Message - A message on the message board of a fantasy league. Messages may include polls. Your application can create a new message or poll, reply to an existing message, or vote in a poll on behalf of the logged-in user.

Metadata

Rules - A list of rules in use in the fantasy league.

Scoring Rules - A list of the scoring rules used in the fantasy league.

Positions - A list of the CBSI position codes used in the Fantasy Platform API.

Stats Categories - A list of the CBSI stats category codes used in the Fantasy Platform API.

Scoring Categories - A list of the CBSI scoring category codes used in the Fantasy Platform API.

For more information on the resources available through the Fantasy Platform API, see the API documentation.

iframe application

Your application will run in an iframe on the CBS Interactive Fantasy Sports interface. Your application must be registered with CBSI for inclusion in CBSSports.com App Central. The App submission and review process is documented here.

When a user selects your application, the CBSI interface will create an iframe for your application and make an HTTP request to your app to populate the iframe. The available real estate in the iframe is 1200 pixels high by 790 pixels wide.

Authenticating the user

Your application will not need to do anything to authenticate the user. The user will launch your application by clicking a link in the CBSI Fantasy Sports site. At this point, the user is already logged in and authenticated using their CBSI credentials. When they select your application, the CBSI site will set up an iframe on the CBSI interface and make an HTTP GET request to your application to populate the iframe. One of the parameters of that HTTP GET request will be an oAuth 2.0 access token. For example:

http://example.com/apps/your-app.html?access_token=xyz123abc789

You will then pass this access token back to the Fantasy Platform every time you make a call to the Fantasy Platform API:

http://api.cbssports.com/fantasy/league/rules?access_token=xyz123abc789

Note that while the access mechanism is oAuth, in this case you do not have to go through any of the normal oAuth steps of sending a request token and redirecting the user to a CBSI login screen. The user is already logged in to CBSI before your application is started in the CBSI Fantasy Sports interface, and therefore you are simply presented with a working access token for the logged-in user. Refresh tokens are not used.

The access token is good for three days. The identity of the user, their league, and sport, are encoded into the access token, therefore all the requests that you make for the Fantasy Platform resources automatically return resources specific to the logged in user. You do not have to take any additional step to identify the user, their sport, or their league. However, the user's ID, league, and sport are also passed to your app when it loads. You can use these to request an after-hours token if the original token has expired. The full call to load your app will therefore look something like this:

http://example.com/apps/your-app.html?access_token=xyz123abc789&user_id=654321zxcvb&league_id=2m8dh47aski3d8hr&sport=Baseball

Requesting an after-hours token

Access tokens expire after three days. This is more than sufficient for a typical interactive session, but there are two scenarios in which you may need to get an access token more than three days after the user's last logon:

• You want to run an automated process on the user's behalf, such as setting a lineup for the user if they are unable to do so for themselves.
• You may need to refresh your app if the user leaves their browser session open for more than three days. In this scenario, the user may return to your app, but when the app tries to access the API, it will get a token expired error. If this occurs, you can either tell the user to reload the app, or you can request a new token. Because the original token was handed to you when your app loaded, and the user's credentials are required to request another one, you can't get a regular token by this method.

To deal with these cases, you can request an "after-hours" token. You request an after-hours token using your own credentials, but supplying the user's id. The after-hours token returned will allow you API access to the user's data, just like the access token originally supplied to your app when the iframe was loaded.

To obtain an after-hours token make an HTTP POST request to the following URL:

https://api.cbssports.com/general/oauth/generate_token

with the following parameters:

• app_id - Your app's login ID
• app_secret - Your app's login password
• user_id - The user's user ID (as provided to you when your iframe was created)
• league_id - The user's league ID (as provided to you when your iframe was created)
• sport - The user's sport (as provided to you when your iframe was created)
• response_format - (optional) The format you want the response in, either XML or JSON (defaults to XML)

For example:

POST /general/oauth/request_token HTTP/1.1
Host: api.cbssports.com
User-Agent: Mozilla/4.0
Content-Length: 49
Content-Type: application/x-www-form-urlencoded
app_id=appLoginID&app_secret=appLoginPassword&user_id=userLoginID&league_id=userLeagueID&sport=userSport

The response will contain your access token, or an error message, if your login fails.

XML response format:

JSON response format:

XML or JSON

The Fantasy Platform lets you choose which format you want to receive a resource in. By default, resources are delivered in XML format, but you can request JSON instead by adding a response_format parameter to the request. For example:

http://api.cbssports.com/fantasy/league/rules?access_token=xyz123abc789&response_format=JSON

The structure of the XML and JSON encodings of a resource are very similar. The same element names and the same structures are use for both XML and JSON. The only difference between the two occurs in the structure of lists. In XML, each item in a list is contained in a named element. Thus a list of players would look like this, with an explicit <player> element:

Because JSON has a list structure built into its syntax, the individual items in a list do not need a named container. Therefore the above list would be rendered like this in JSON:

Other than this difference, the XML and JSON returned by the Fantasy Platform will be structured identically.

The Fantasy Platform API documentation provides explanations of every field in the resource. Because the resources can have deeply nested structures, the API documentation uses XPath expressions to unambiguously identify every field. Thus you will see a field definition written like this:

          /draft_order/picks/pick/team/@id
          The ID of the fantasy team. You can get a list of team IDs and their expansions by requesting the Fantasy Teams resource.

If your are using JSON, remember that the element names of list items are omitted from the JSON structure, so the "pick" element of the path above would not be present in the JSON example.

The resource envelope and HTTP responses

As a RESTful interface, the Fantasy Platform uses HTTP response codes to indicate the success or failure of a request. The XML or JSON response is contained in an envelope that also includes the HTTP response code. In XML, the response envelope consists of two elements which contain the body of the response. These are the <result> element and the <body> element. They look like this:

In JSON, the envelope looks like this:

Note than when field paths are described in the API documentation, the envelope elements are not included in the XPaths. The resource itself is the stuff inside the envelope. The envelope is not treated as part of the resource when describing the resource.

The envelope contains four attributes. The statusCode and statusMessage attributes contain the HTTP status code returned in response to the request. These attributes will match the HTTP status code and message returned in the HTTP packet itself. Note that you should not rely on the status code in the envelope alone, since some error conditions could mean that no resource is returned, and thus no envelope is present. You should always check the HTTP status codes themselves to make sure your request was successful.

The uri attribute contains the URI of the resource. The uriAlias attributes contains an alias for the resource. The alias is specified by the developer when they call the FOPE API using the CBS Interactive JavaScript API library. If you are using the CBS Interactive JavaScript API library, you can make request for resource asynchronously and then use the uriAlias to identify the resources returned.

IDs and Abbreviations

A number of APIs require that you specify a particular ID in order to retrieve a particular resource. For instance, to get updates for a pro player, you must pass the player's ID to the Updates resource. Every ID that is required by any API can be found by requesting other APIs. Similarly, some of the information in some resources uses IDs or abbreviations to stand for complex data. For each of these IDs and abbreviations, there is a resource that you can use to decode the ID or abbreviation and get the full data.

The API documentation provides the names of the resources you can use to find or decode IDs and abbreviations for every request and every field. The following lists summarize the major IDs and abbreviations used in the Fantasy Platform, where they come from, and where they are used.

Messages and polls

You can provide the ability for the logged-in user to create message board messages or polls, to reply to a message, vote on a poll, or delete a message.

The normal method for handling messages is to first request the Messages resource to get a list of messages and allow the user to select a message to read. When the user selects a message, request the Message resource with the message ID to show the message.

You can then provide the user with the ability to reply to the message. To reply to a message, you use the POST method to create a new Message resource, and supply the ID of the current message in the reply_to_id parameter.

To create a new message, you use the POST method to create a new Message resource but do not supply a reply_to_id parameter.

If the current logged-in user is the author of a message, you can provide them with the ability to delete the message. You can delete a message using the DELETE method and specifying the ID of the message to delete?

Trades

You can provide the ability for the logged in user to offer a trade to another team. How the trade proceeds will depend on the trade rules for the the league. You can determine the trade rules for the user's league by requesting the Rules resource. The actual trade rules are enforced by the Fantasy Platform system, not your application.

To offer a trade, you create a Trade resource using the PUT method to create a new Trade resource. The trade is then in the offered state. When the owner of the team to which the trade is offered logs in and requests the Trades resource, they will see your trade offer in the list of Trades.

What happens then will depend on the trade rules for the league. The Fantasy Platform API lets your application accept, reject, withdraw, vote, approve, or disapprove a trade on behalf of the logged in user by POSTing an edit to the trade resource. The Fantasy Platform API will only accept those edits that are in accordance with the trade rules for the league. Your application should consult the Rules resource for the league to determine which options you should offer to the user for a trade in a particular state.

Once the trade has been processed according to the rules governing the league, the Fantasy Platform system will then execute the trade or delete the trade resource if the trade was rejected. The result of the trade can be determined by requesting the Trade resource with the trade's ID and examining its status.

Making lineup changes

You can provide the ability for the logged-in user to change the lineup on their fantasy team. To get the current linup, request the Rosters resource.

Testing your application

To test your application, you can create a test leagues on the Development Center Home page. You must be a registered developers (basic and premium) to create a test league.