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.
The resources available through the Fantasy Platform cover the following areas:
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.
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 Owners - A list of owners in a fantasy league.
Trades - A list of trades in a fantasy league.
Message List - A list of messages on the message board of a fantasy league.
Rules - A list of rules in use in the fantasy league.
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.
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:
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:
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.
POST /general/oauth/request_token HTTP/1.1
The response will contain your access token, or an error message, if your login fails.
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:
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 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.
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.
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.
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.
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.