API Docs Test the API Right Here!

The API hews as closely as possible to the REST architectural style. The API is organized around a set of resources that populate the world of endurance racing, like events, races, race entries, etc. With the API, your application can perform operations on these resources through the HTTP protocol. You can use the documentation below to learn about the API. In particular, you can test out API calls right here on this page to see exactly how API calls work and how to incorporate them into your application.

Terminology

A resource is some object of interest targeted by the API. In the world of endurance racing this includes events, races, athletes, timing devices, and others. We'll refer to a specific resource sometimes as a resource entity to distinguish that specific entity from all entities of that resource type. A resource collection is a number of resource entities of the same type.

The ChronoTrack Live Open Platform API is comprised of operations on these resources. All operations are executed by sending HTTP requests to one of our API endpoints. An API endpoint is a URI to which a API request is directed.

Endpoints

All API requests should be sent to one of the following two endpoints:

The production endpoint should only be used in live, production code and never for testing. The production endpoint is backed by the ChronoTrack Live production database, which means all changes to data via the production API will be immediately visible to ChronoTrack Live users.

The testing endpoint is backed by a separate testing database that is refreshed every night with a copy of the production database. This means any API activity that changes data via the testing endpoint will have those changes disappear the next day. Please note the QA environment is not 100% guaranteed up at all times as it is a test environment.

Security

All requests to our production API must be through the secure HTTPS protocol. Any requests that come in on a non-secure port will be redirected to our TLS/SSL secured service.

All requests must also be authenticated. First, a request must originate from an application that is registered and approved by ChronoTrack. Second, the application must authenticate the ChronoTrack Live user on whose behalf it is making requests to our system.

Supported Authorization Methods

We support four authentication methods, each suited for a different kind of application environment. For applications that have easy access to the user's browser, like a web or mobile application, we support the OAuth 2.0 Web Flow. For applications without browser access, like native desktop/laptop applications, we provide two alternatives. If the environment your application operates in has the capacity to securely store your users' ChronoTrack Live account credentials, then you can use HTTP Basic authentication. If you can't, or prefer not to, locally store your users' credentials, we support the OAuth 2.0 Password Flow.

Finally, for certain testing environments where data security requirements are minimal, we support a simple authentication scheme where you can pass a user id and password as parameters to the API call. All our methods are described in detail below.

OAuth2 Web Flow

Web applications can acquire an OAuth2 access token for a ChronoTrack Live user by following these steps:

1. Obtain a ChronoTrack Live developer account here. Creating a developer account will also register your client application.

2. Your application will be assigned a client_id and a client_secret. The client_id is public information, but you should take care to safeguard your client_secret. During the process of registering your application with us, you will be asked to provide a redirect_uri, that is, a URL within your web application where users will be redirected after granting your application permission to access their ChronoTrack Live resources. An example redirect_uri is:

   https://mywebapp.com/oauth2

3. When the user first invokes a function in your application requiring access to their ChronoTrack Live resources, you should redirect the user to our authorization end-point:

   GET /oauth2/authorize?response_type=code

   Make sure to add a Basic HTTP Authorization header to this request using your client_id and client_secret as the username and password. This is required to verify the authorization request is coming from your application. See the specific instructions in the HTTP Basic Authentication section for the mechanics of how to construct the Authorization header.

   This will redirect your user to our authentication service. They will have to login as they normally would to ChronoTrack Live. They then will be presented with a screen that allows them to grant your application permission to access their ChronoTrack Live resources.

4. Upon authorizing your application, the user will be redirected back to your application's specified redirect_uri:

   https://mywebapp.com/oauth2?code=bef10603874b

   The code parameter appended to your redirect uri is a short-lived (10 minutes), single-use authorization code that your application can convert into a longer-lived access token.

5. To obtain an access token, your application should make a GET API call to our token endpoint:

   GET /oauth2/token?grant_type=authorization_code&code=bef10603874b

   passing in the code parameter returned to your application in the last step and making sure to add an Authorization header that provides Basic HTTP authentication for your client app (using your client_id as the username and your client_secret as the password).

   This API token endpoint will return a json formatted object containing an OAuth 2.0 access token that allows your application to access the user's ChronoTrack Live resources for a lengthy period of time (usually 72 hours).

   {
     "access_token":  "2YotnFZFEjr1zCsicMWpAA",
     "token_type":    "Bearer",
     "expires":       "1343309220",
     "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
   }

   You also will receive a refresh token that you can send to our token endpoint to receive another access token, good for another 72 hours of use. The refresh token is valid for one year or until the user revokes your application's access to their resources.

   You send a refresh token request like this:

   GET /oauth2/token?grant_type=refresh_token&refresh_token=597262138b23

   making sure to again provide Basic HTTP authentication for your client app (using your client_id as the username and your client_secret as the password). This will send you another access token that you can use for another 72 hours. It will also return a new refresh token that you can use to extend your access.

6. Finally, with a fresh access token, you can make API requests, like getting a list of events the user has access to:

   GET /api/event

   making sure to pass in an Authorization header with the access token like so:

   Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

OAuth2 Password Flow

For applications where the OAuth2 Web Flow cannot be used (for example, native applications without a browser layer), an OAuth access token can be acquired by making a single call to our token endpoint and passing the end-user’s ChronoTrack Live account credentials as the username and password parameters with a grant_type of password.

GET /oauth2/token?grant_type=password&username=joesmith%40someplace.com&password=some_password

HTTP Basic Authentication

This method involves passing in the resource owner's ChronoTrack Live account username and password directly, according to the HTTP Basic Authentication protocol. You simply construct an Authorization header as follows:

1. Obtain the resource owner's ChronoTrack Live account credentials. For example, you could provide a dialog through your application asking for their ChronoTrack Live account username and password requesting their permission to use those credentials for accessing their account data on their behalf.
2. Concatenate their username and password with a colon (:). For example, if their username is "zooba" and their password is "tooba", you would construct the string zooba:tooba.
3. Now base64 encode that concatenated string to produce: em9vYmE6dG9vYmE=.
4. Finally, add an authorization header to your request like this:

   Authorization: Basic em9vYmE6dG9vYmE=

Test Auth Scheme

In certain situations, like when using our docs here to test the API, security requirements are minimal and using oauth or basic authentication is infeasible. For these special cases we support a simple method of passing in the ChronoTrack Live resource owner credentials via parameters. For instance, if you have a test account for a resource owner called test-user@myorg.com with password 12345, then you could make authenticated requests to our API on behalf of that test user:

GET /api/event?client_id=abcdefgh&user_id=test-user%40myorg.com&user_pass=12345

To prevent exposing the password, you should SHA1-encode the password:

GET /api/event?client_id=abcdefgh&user_id=test-user%40myorg.com&user_pass=8cb2237d0679ca88db6464eac60da96345513964

Formats

The following table describes the formats used for the content of API requests and responses. The first column contains a short format code for each format, while the second column contains the standard Internet Assigned Numbers Authority MIME type for the format.

Requests

API requests to our servers are just standard HTTP requests. As with all HTTP requests, a request to our API always contains a method which denotes the operation to be done, always has a URL (specifying the resource to operate on), usually has some parameters you send to qualify your request, and sometimes those parameters are specified in the URL itself, sometimes in the request headers and sometimes in the request body (formatted as JSON, XML, or CSV). We'll look at each of these request components in this section.

Request Methods

Request URL

The URL path specifies the resource or resource collection the request operates on.

/api/{resource-name}.{format}/{resource-id}/{sub-resource-name}?{url-params}

Request Parameters

Most API requests will have one or more parameters that define some context for the request. For instance, all requests must specify the client_id parameter, which identifies the application the request originates from. The request parameters may be specified in several different places, including the URL path, the URL query, the request header and the request body. We'll consider each in turn.

URL Path Parameters

Two optional, but significant, parameters are commonly specified in the path of a URL request. First, the resource_id of the resource being operated on. Second, the desired format of the response. The following example illustrates the use of both of the parameters to request a particular event's properties in xml format:

GET /api/event.xml/123

URL Query Parameters

The query portion of a URL is the list of parameters that comes after the question mark following the URL path. If more than one parameter is specified, it must be separated from the others by an ampersand (&). The following URL requests the details for event 123 in xml format for the client application with id abcdef:

GET /api/event.xml/123?client_id=abcdef

Instead of specifying the format of the request in the URL path, you could instead specify it as a query parameter:

GET /api/event/123?client_id=abcdef&format=xml

Header Parameters

Request headers can also be used to specify context for a request. The following table provides a list of headers you can use with API requests.

Body Parameters

Common API Request Parameters

The following table enumerates some commonly used request parameters and where they are usually included in the request.

Rate Limiting

When 1500 concurrent connections, from the same IP address, are reached within a 60 second time frame, the user will be blacklisted for the remaining duration of that time frame and will receive the 503 over rate error.

Responses

An API response from our servers has several salient characteristics worth drawing attention to. First, each response has a numeric HTTP code that indicates success or failure. Second, a response usually contains a body formatted as JSON, XML, or CSV that contains the data you requested. Third, for many requests that return multiple entities (like a list of all events your user has access to, for instance), there are headers in the response that contain useful information on the size of the total result set and what portion of that total result set the current body of the request contains. We'll elaborate on each of these in turn.

Response Codes

Response Bodies

For responses that return content (basically all responses except PUT and DELETE) the format of the response body can be set to one of several alternatives.

You may specify the response format you want in one of two ways. First, you can add an Accept header to your request with the appropriate MIME type for your preferred format. Second, you can add an extension to the resource name in the URL (for example, to request a list of all accessible events in XML format, you could use GET /api/event.xml. If neither of these methods is used, the response format defaults to JSON. The proper extension is just the lower-case form of the name in the table above.

Response Headers

Character Encoding

We use UTF-8 encoding through and through to guarantee proper encoding of all international character sets. All data you send to an API endpoint is assumed to be, and therefore must be, encoded in UTF-8. All data transmitted from an API endpoint is encoded in UTF-8.

Data Types

The API uses a pretty standard collection of types for all data that it processes, as described below.