API Overview

Last updated: Tue, 02 Dec 2014 18:40:48 +0000

Location and Version

The ITTF API is located at http://api.ittf.com/1. The "1" at the end of the url is the version number of the API. Currently, there is only one version; 1.

Schema

The ITTF API has a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. You may retrieve the most current schema at anytime from http://api.ittf.com/schema.json

To retrive a specific version of the schema, add the version number to the base url, like so http://api.ittf.com/{version}/schema.json

Security and Authentication

This API is not yet public. CORS is disabled. Therefore, it only accepts requests from *.ittf.com.

Response Format

All responses will be sent as valid JSON and will include a meta property containing a meta object.

Meta Attributes

Name Type Description Example
message string Additional info regarding the response "Success."
refreshInterval nullable integer indicates the frequency in milliseconds at which new content is pulled from the underlying data source 15000
lastUpdated nullable date a UTC date in ISO 8601 format that specifies when the contents returned in the response were last retrived from the underlying data source. Typically this is only returned for GET requests. 2014-12-02T11:01:00Z
error nullable integer if an error has occured, this property will be the 3 digit http response code corresponding to the error 400

Responses to GET Requests

GET requests will also include a data property containing an array of the requested resources. If no resources match your request, data will be a zero-length array.

Example Response Showing Meta

{
    "meta": {
        "message": "Success."
    },
    "data" : [{
       ...
    }]
}

Null Values

In order to reduce the amount of data being sent over the wire, if a resource contains properties that are nullable, those properties may be omitted when their value is null. Note, in the above example the refreshInterval was null and therefore ommited from the Response.

Also, resources that contain arrays of other resources will generally omit those arrays unless specifically requested via an include paremeter on the request (not implemented).

Additional Properties

By default, the API attempts to return the smallest useful version of a resource possible. Generally, this means that any properties which are arrays of other resources will be ommited from the standard response, except in cases where ommiting them would render the response uesless. For example, the Match List endpoint will ommit the stats property from the list of matches returned, but will include the games property.

This also means that any properties which are of type object

Request Format

Requests should be sent using conventional URL query strings wherein a set of key/value pairs sperated by an & and prepend by a ? are sent to the endpoint URL.

Example Request with Query String

http://api.ittf.com/1/matches/?tournamentId=1111&eventType=MS

Note: the / before the ? must not be ommitted. The endpoint address will not be valid if called without it.

Caching

Some responses from the API are cached. When this is the case, the meta attribute of the response will include a refreshInterval property that indicates the frequency in milliseconds at which new content is pulled from the underlying data source. If a caller makes the same request more than once within a single refresh interval, the response will be the same as the first call, regardless of changes to the underlying data source.

Error Handling

The api will set an appropriate HTTP status code and will include a message and error code in the meta field of the response that describe the error.