Getting Started

Introduction

Matchbook provides a RESTful API to facilitate integration between tools and applications and our Betting Exchange. RESTful APIs are HTTP based meaning that any tools and programming languages capable of making HTTP requests can use the Matchbook API.

The key characteristics of the API include:

• A resource-oriented URL structure
• Supports HTTP verbs including GET, PUT, POST and DELETE
• Makes full use of HTTP response codes such as 2xx Successful, 3xx Redirection, 4xx Client Error, and 5xx Server Error
• Observation of HTTP caching features including the cache-control directive

Data Format

The API supports two data formats, XML and JSON.

The desired response data format is specified by setting the Accept HTTP header to either "application/xml" or "application/json". Responses from the Matchbook API will include the Content-Type header with the value of "application/xml" or "application/json" to indicate the data format contained in the response. Requests that include a payload such as login and submit offers require the Content-Type header to specify the data format of the request body.

Matchbook recommends the use of JSON. It is a more compact format and will yield better response times due to its smaller size.

Security / Authentication

All requests to the Matchbook API should use https. The Matchbook servers will redirect http requests to https.

Matchbook provides a login API that returns a session token value in the response and in a HTTP cookie called "session-token". All subsequent requests to the other API endpoints should include this session token as either a cookie called "session-token" or a HTTP header called "session-token".

Many HTTP clients automatically handle cookies. If using a client that does then the session-token cookie will be automatically included with all requests after making the initial login request.

Localisation

Matchbook supports the use of multiple currencies, odds types and exchange types. The API will select defaults for each of these based on the most commonly used types in the region the API requests originate from. It is possible to override these defaults by providing values for currency, odds-type and exchange-type parameters to the relevant API endpoints. Details are included in the API reference for each endpoint where these are supported.

Error Handling

The Matchbook API uses standard HTTP status codes to indicate successful or error responses. The most common status codes are listed below.

In addition to the status code error responses will also include a response body containing more detailed information e.g.

{
  "errors": [{
    "messages": ["Username or password are incorrect."]
  }]
}

<response>
  <errors>
    <error>
      <messages>Username or password is incorrect.</messages>
    </error>
  </errors>
</response>

Compression

The Matchbook API supports optional compressing of the response data using GZIP compression. It can be enabled by including the HTTP Accept-Encoding header with a value of "gzip" on each request. The response will include the HTTP Content-Encoding header with a value of "gzip" to indicate that the response is compressed.

Matchbook recommends enabling compression as it makes the response size smaller which will result in lower bandwidth usage and faster response times.