Getting Started
MileSplit has created an open platform to interact with its backend database for both internal and external use. We want to allow others to leverage this data on other sites to add value to the third party service, to MileSplit, and especially to our users.
Terms of Use
- While we strive to keep these APIs open to other services, we reserve the right to deny anyone access to, change, or discontinue the service at any time for any reason.
- You must identify conspicuously adjacent to the service that the data is being supplied by MileSplit. You may use a MileSplit logo or other identification in doing so, provided that you do not in any way misrepresent your service as being run by or sponsored by MileSplit.
- You may not sell or charge for access to data provided by this API. You may not re-distribute or syndicate or otherwise repackage this API for use by others.
- You may not try to reverse engineer or hack any of the API methods or processes.
- We may change the terms of service at any time and will publish updated documentation on the developer’s portion of the web site.
- We may impose rate limits on services or IP addresses that access large amounts of data or make frequent calls.
- You may not store or scrape any of this data under any circumstances. You may store only name and ID references obtained from the API, other than temporary caching. You may not store any information about a user account other than the user name and token.
RESTful Interface
The API is written in a REST format. All requests to select data should use the HTTP GET request method. Inserts or updates must use the via HTTP POST request method. PUT and DELETE request methods are not currently supported since they are difficult to implement in client-side code.
Response Format
Currently we only support JSON responses, with the option for JSON-P. We may add other formats in the future including XML, RSS, or Atom.
Structure of an API Request
All requests should be directed at the following base URL end point:
The method of the API call will follow. For example the method test/echo looks like this:
http://api.milesplit.com/test/echo
Typically at least one additional parameter is placed in the URL:
http://api.milesplit.com/test/echo/Hello+World
Setting the response format will be done with the equivalent of a file extension. As of now only JSON responses are supported, so it makes no difference. However, it is recommended to include the format extension so that your code will remain compatible if we add other formats. The response will be specified like this:
http://api.milesplit.com/test/echo/Hello+World.json
Method Permissions
There are four permission levels for methods. Note the background colors as these colors will be used in the documentation to denote what each method is.
- Public –Any developer may utilize these without even needing to apply for an API Key. This level may be removed or further limited in the future, so it is recommended that any application (other than for testing purposes) get registered with us and sign your methods with application authorization.
- Private – Only applications with a valid API Key may access these methods.
- Authentication Required – This requires the user of the API to have authenticated with credentials of their MileSplit account. Mostly any insert or update access will require this.
- Closed – These methods are used internally and may be opened to certain authorized partner applications–decided case by case upon request.
.
There is a chapter dedicated to user authentication and application authorization.
Cross Domain Javascript Access with JSON-P
Most modern browsers have security policies that do not allow a web site to call the content of another web site (or API) on another domain. This puts a huge damper on the useful ness of the API unless you resort to a server-side proxy or other unnecessary complications.
JSON-P is perhaps the simplest way to work around these limitations. While the security policies forbid you from accessing API data via XMLHttpRequest (which is the normal AJAX go-to object), the browser will allow you to include a javascript file from another domain in your site that can in turn talk to each other. JSON-P builds on this loophole. Essentially it works by including (typically dynamically) the API call as a script (in a script tag). The API returns JSON data with “padding” (the P in JSON-P) that will hit a callback method.
We provide support for this cross-domain Javascript integration by allowing you to specify a callback function to receive the response. Simply add the callback parameter to the query string:
http://api.milesplit.com/test/echo/Hello+World.json?callback=receiveResponse
Here is some sample Javascript that you may utilize:
var Request = function(url, callback) {
var s = document.createElement(“script”);
s.src = url + ‘?callback=’ + callback;
document.getElementsByTagName(‘head’)[0].appendChild(s);
};
function received_json(response) {
alert(response.message);
}
new Request(‘http://api.milesplit.com/test/echo/hello.json’,’received_json’);
Various Javascript frameworks, such as jQuery, also have automated ways to handle this process.
There are three possible response types, depending on what method you are performing:
Successful Object Response
When you are requesting a certain object (athlete, meet, team, etc) then the API will return to you a representation of that object with its properties. This object will appear as the root element. Here is a JSON example:
{ “ID”: “25”, “FirstName”: “Matt”, “City”: “St. Petersburg”, “State”: “FL” }
Successful Array Response
When you are requesting a list of items, such as doing a search or asking for statistics, then the API will return an array of data to you in the data property. For example:
{ “data”: [
{ “ID”: “1051485”, “FirstName”: “Jerimy”, “City”: “Leesburg”, “State”: “FL” },
{ “ID”: “1383724”, “FirstName”: “Jerimy”, “City”: “Coconut Creek”, “State”: “FL”}
] }
Successful String Response
If an insert, update, delete, or other executable is being performed then the API will respond with simply a text response with the value in the message property. For example:
{ “message”: “yo dawg” }
Error Response
It is easy to test for an error because the error object will exist in the root element of the response. There are two properties provided for this object: type, which will be a numeric error code, and message, which is a human readable error message.
Here is what the response may look like in JSON:
{ “error”: { “type”: “2”, “message”: “Did not find a method called eat/chicken” } }
Limits and Pagination
For requests that return a list of data, it may be possible to do pagination requests or to set how many items you want returned. In all cases, the API will set limits on how high your limit can be and how deep you can navigate into the data.
To specify where you want to start and how many to return pass in these values in the query string:
- limit = The number of results to return. Maximum limits will be enforced, which vary by method and request type.
- offset = The record number that you want to start with. Zero is default. How deep you are able to dig will have limits enforced, which vary by method and request type.
Limiting Fields Returned
Pass in the fields parameter in the query string as a comma-separated list to specify which fields you want returned to you in the response. Otherwise, it will return the defaults.
MileSplit Developer Blog 