Open Transport is a set of JSON/RESTful endpoints which should already feel familiar to developers. They all follow a series of good practices, which are described in this section.

HTTP requests

All features are modelled via RESTful APIs, and developers are mearly changing the state of resources in order to acheive their goals.

The key aspects of any request are:

The HTTP method
The path of the request
The body (a string of encoded JSON)

The key aspects of a response are:

The HTTP status code
The body (a string of encoded JSON)

HTTP methods

Unless specified otherwise, all APIs will follow these rules:

GET requests are for retreiving information (like getting an object, or making a query) - No state will change
POST requests are for adding/creating new resources
PUT requests are for updating existing resources
DELETE requests are for removing a resource

Request paths

The URL is made up of four main segments:

https://opentransport.com/api/beta/path/to/resource?q1=one&q2=two

https://opentransport.com/ - (static) The scheme and host is always the same
/api/beta - (static) The API path prefix indicates which version of the API you are using (currently /api/beta)
/path/to/resource - (dynamic) The path of the request (indicates which resource to interact with)
?q1=one&q2=two - (dynamic) URL parameters adds information to GET and DELETE requests

Static elements are always the same, where dynamic elements change depending on what the request does.

Request Bodies

POST and PUT requests usually come with a body. The request body is an encoded JSON string that describes the resource. For example, to represent a Monkey the request body might look like this:

{
	"type": "primate",
	"name": "Monkey",
	"kind": "Mandrill",
	"lineages": ["New World Monkeys", "catarrhines"],
	"description": "Monkeys are haplorhine primates, a group generally possessing tails and consisting of about 260 known living species",
	"lifespan_years": 20,
	"can_be_pet": true,
	"more": "https://wikipedia.org/wiki/Monkey"
}

Information is represented in key/value pairs using special characters to indicate pairs, strings, arrays, etc.

To learn more about JSON, see http://www.json.org/

Request headers

All requests to Open Transport using JSON/HTTP should set the following headers to indicate the format of the bodies, and the acceptable response encodings:

Content-Type: application/json; charset=utf-8
Accept: application/json; charset=utf-8
Authorization: Bearer YOUR_API_KEY - for more information, read about Authorization

Errors

If an API request results in an error, you will receive a non-2xx response code, and a document payload that contains a description of the error:

{
	"error": "Oops, something went wrong"
}

The error field is only ever present if something went wrong, otherwise it is always omitted.

Cursors

A Cursor is a special string that allows you to retrieve multiple pages of results from some APIs. Use the cursor from a previous request in new requets if you want to skip to the next result in a larger set than spans HTTP requests.

You specify the cursor with the ?cursor URL parameter.

Make the first request without a cursor value, and you will get a next_cursor field in the response:

{
	// other fields
	"next_cursor": "abc123"
}

The cursor values are long and ugly strings that are subject to change at any time so you should not store them or rely on them long term.

Use that cursor value from the first request in the next request to get the next page.

Data types

The API endpoints speak JSON, which means the following types are supported:

string - A string of alphanumeric characters - for example "My Name"
number - An integer or floating point number - for example 1 or 50.123
bool - Either true or false
datetime - A string containing a date and time in RFC 3339 - for example "2017-08-27T21:45:58.870685072Z"
arrays - A set of values
objects - A map of key/value pairs - keys are strings, values are any acceptable type

Geo object (position)

To refer to a physical location, Open Transport uses the following structure:

{
	"lat": 50.1,
	"lng": 0.12
}

lat - (number) Latitude
lng - (number) Longitude

API Basics