The Race Server's API

The race server API accepts JSON data for a single racing buggy via HTTP POST and saves it in the database. It lets you upload your buggy data programmatically, instead of copying-and-pasting it into the web form.

If you don't have an API key yet (check your API settings page), ask us to issue you with one. You only need this when you get to task 4-API.

An important difference between using the API and the web form — which also generates an HTTP POST request — is that you can only access the web form during an authenticated session (that is, you must log in before the server will let you get to it). The API uses explicit credentials (a key and a secret) to determine if the requester is allowed to update the buggy.

HTTPS

Note that the API uses Transport Layer Security (TLS) — you can tell because the endpoint URL starts with "https://". So although this specification refers to HTTP (Hypertext Transfer Protocol) methods, the requests and responses are being transported over a secure layer.

Request

The server accepts HTTP POST requests to this endpoint:

Endpoint URL
https://rhul.buggyrace.net/api/upload

The request must provide these four items of data (name/value pairs):

Name Value
user The buggy owner's username on the race server
key The API key for this user (which was set by staff)
secret The API secret for this user (which was set by the user)
buggy_json The JSON data describing the buggy (properties with names and values according to the race specs)

Response

The server responds with a JSON payload (MIME type application/json). If any of the authorisation credentials were rejected, a response code of 401 is returned, otherwise 200.

A response with 200 does not necessarily indicate success: you must inspect the content (JSON) of the response to determine the success of the update operation. It will contain an error property (with a string message as its value) if anything went wrong, otherwise it will have an ok property. Note that the update operation is forgiving about bad values (according to the the race specs) and silently replaces them with defaults — so you'll get an ok even if some or all of the properties in your JSON were ignored and substituted with default values instead.

Code JSON payload
Example success response:
200 {"ok": "buggy updated OK"}
Example failure responses:
401 {"error": "missing API key"}
200 {"error": "Failed to parse JSON data"}