66laps Developers

« Back to the developer homepage

Raceio API

Martin Galpin (m@66laps.com)

Version 1.0

6th October 2010

Introduction

Raceio exposes data via a RESTful Application Programming Interface (API). The API enables third party applications to integrate and build on the Raceio platform.

Authentication

Raceio currently supports HTTP basic access authentication, either over standard HTTP or encrypted HTTPS. It is highly recommended that encrypted HTTPS is used whenever possible. For more information on HTTP authentication schemes please refer to RFC 2617.

The HTTP_AUTHORIZATION header should be sent with each request and include a Base64 encoded, colon separated username and password.

Basic <base64 username:password>

If authentication was not sent or if authentication was unsuccessful, the server will respond with the HTTP status code 401 and a challenge header in the form:

WWW-Authenticate: Basic realm="Raceio API"

Requests

The Content-Type and Accept headers should be set to application/json in order to identify the request and response type.

Responses

The Raceio API will return responses in JavaScript Object Notation (JSON). Additionally, Raceio will attempt to return the appropriate HTTP status code for every request.

  • 200 OK - The request was successful. This is the most common response code.
  • 201 Created - The request was successful and the resource was created. See Upload a new session.
  • 204 (empty body, see RFC2616) - The resource was successfully deleted. See Delete session.
  • 400 Bad Request - The request was invalid. See the response error message for further information.
  • 401 Unauthorized - Authentication was missing or incorrect.
  • 403 Forbidden - The request was refused. See the response error message for further information.
  • 404 Not Found - The URI was invalid or the request resource does not exist.
  • 409 Conflict - The exact file already exists. See Upload a new session.
  • 415 Unsupported Media Type - The file type was not recognised. See Upload a new session.

Dates

All dates and times will be represented in the ISO 8601 format.

Users API

The Users API provides read-only access about given users.

Get

Current user

This will return information about the current authenticated user.

Request
GET /api/users/me.json
Response
{
    "id": 672,
    "username": "mschumacher",
    "first_name": "Michael",
    "last_name": "Schumacher",
    "last_login": "2006-12-17 07:03:31",
    "email": "m.schumacher@mercedesgp.com",
    "date_joined": "2006-12-17 07:03:31"
}

Get user

This will return the public profile of the referenced user.

Request
GET /api/users/#{username}.json
Response

The values for first_name, last_name, location and website are optional and depend on the given users privacy settings.

{
    "id": 672,
    "username": "mschumacher",
    "first_name": "Michael",
    "last_name": "Schumacher",
    "location": "Silverstone, UK",
    "website": "http://www.mercedesgp.com/"
}

Search users

This will run a search for users with public profiles on Raceio. The parameter q specifies the query to run against public profiles. Two further optional parameters are available: page and per_page (default and maximum of 25) that enable pagination.

Request
GET /api/users/search.json?q=#{query}
Response
[{
    "id": 672,
    "username": "mschumacher",
    "first_name": "Michael",
    "last_name": "Schumacher",
    "location": "Silverstone, UK",
    "website": "http://www.mercedesgp.com/"
},
{
    "id": 673,
    "username": "nrosberg",
    "first_name": "Nico",
    "last_name": "Rosberg",
    "location": "Monte Carlo",
    "website": "http://www.mercedesgp.com/"
},
...]

Session API

The Session API provides read-write access to sessions within Raceio.

Get

Get sessions

This will return the most recent sessions for the current authenticated user. Two optional parameters are available: page and per_page (default and maximum of 25) that enable pagination.

Request
GET /api/v1/sessions/?page=#{page}&per_page=#{per_page}
Response

An array of session objects will be returned.

A session object will contain associated metadata, a URL to download the data file and a collection of Raceio specific properties such as its id, the date it was uploaded, the session type and the session status. The purpose of the response is not to give an in-depth representation of each session but instead to give a summary of its contents.

A metadata property exists for each field declared in the OpenMotorsport file format. As such, there are both mandatory and optional fields. See the OpenMotorsport specification for more information.

The property status indicates the current status of the session within Raceio. It will be either:

  • Queued - the session was recently uploaded and is awaiting processing.
  • Processing - the session is currently processing.
  • Complete - the session was successfully processed.
  • Failed - the session failed to process.
  • Unsupported - the session is not an officially supported format. For a list of formats, see Supported file types.

The property type indicates the particular discipline:

  • Closed - the session contains laps (e.g. circuit racing).
  • Open - there are no laps (e.g. rallying or drag racing).

This property will be omitted if the session status is Unsupported.

Example
[{
    "id": 2,
    "url": "https:/dl.raceio.com/sessions/dea3fd8c-d47e-11df-a423-0017f23094bd",
    "laps": [
        77121,
        66208,
        64248,
        63387,
    ],
    "user": 1,
    "uploaded_date": "2010-10-10 15:58:41",
    "type": "Closed",
    "status": "Complete"
    "metadata": {
        "date": "2010-08-23 17:48:06",
        "datasource": "rFactor",
        "venue": {
            "name": "Northamptonshire International"
        },
        "user": "mwg",
        "vehicle": {
            "name": "LUCAS Pro Comp #19"
        }
    }
},
{
    "id": 3,
    "url": "https://dl.raceio.com/sessions/f759e78c-d47f-11df-94de-0017f23094bd",
    "user": 1,
    "uploaded_date": "2010-10-10 16:06:32",
    "type": "Open",
    "status": "Complete"
    "metadata": {
        "date": "2010-08-23 17:48:06",
        "datasource": "rFactor",
        "venue": {
            "name": "Northamptonshire International"
        },
        "user": "mwg",
        "vehicle": {
            "name": "LUCAS Pro Comp #19"
        }
    }
}
...]
Status Codes
  • 200 - the request was successful.

Get session

This will return information about a given session specified by a session id.

Request
GET /api/v1/sessions/#{session_id}.json
Response

A single session object will be returned. For more information, see Get Sessions.

Status Codes
  • 200 - the session was successfully retrieved.
  • 403 Forbidden - the session exists but the current given does not have access to it.
  • 404 Not Found - the session does not exist.
Example
{
    "id": 3,
    "url": "https://dl.raceio.com/sessions/f759e78c-d47f-11df-94de-0017f23094bd",
    "user": 1,
    "uploaded_date": "2010-10-10 16:06:32",
    "type": "Open",
    "status": "Complete"
    "metadata": {
        "date": "2010-08-23 17:48:06",
        "datasource": "rFactor",
        "venue": {
            "name": "Northamptonshire International"
        },
        "user": "mwg",
        "vehicle": {
            "name": "LUCAS Pro Comp #19"
        }
    }
}

Post

Upload a new session

This will create a new session from an uploaded file. You should post the file using a multi-type encoded form according to RFC 1867. The Content-Type should be application/octet-stream. If the Content-Disposition header is included, the original filename will be retained.

Response

Raceio will apply pre-processing to the file to determine if it is of a recognised type. If the file type is recognised, a single object will be returned containing the new session id.

Example
{
    "session_id": 1
}
Status Codes
  • 201 Created - the session was successfully created.
  • 400 Bad Request - the form was incomplete.
  • 409 Conflict - the exact file has already exists.
  • 415 Unsupported Media Type - the file type was not recognised. See Supported file types.

Delete

Delete session

This will delete a given session specified by a session id. Note that for security, a session cannot be permanently deleted using the API. A deleted session will remain in the users trash until it is manually deleted via the website.

Request
DELETE /api/v1/sessions/#{session_id}.json

Response

Status Codes
  • 204 (empty body, see RFC2616) - the session was successfully deleted.
  • 403 Forbidden - the session exists but the current user does not have access to it.
  • 404 Not Found - the session does not exist.

Appendix A: Supported file types

Raceio currently supports the following file types. If a file type is fully supported, it is available for analysis, sync and backup. However, file types that are only partially supported can still be uploaded and are available for sync and backup immediately. They will be automatically enabled for analysis when support is available.

Filetype Level of support
OpenMotorsport Full support.
Live For Speed Replay Analyser Format Full support (and conversion to OpenMotorsport).
Pi Research System I/II (.s1a, .s2a) Partial support.
MoTeC i2 (.ld) Partial support.

Appendix B: Version History

Date Version History
14/10/2010 1.0 Initial release

Appendix C: License

Copyright © 2010 66laps Limited.