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.
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 key aspects of a response are:
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 changePOST
requests are for adding/creating new resourcesPUT
requests are for updating existing resourcesDELETE
requests are for removing a resourceThe 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
requestsStatic elements are always the same, where dynamic elements change depending on what the request does.
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.
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 AuthorizationIf 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.
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"
}
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.
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 valuesobjects
- A map of key/value pairs - keys are strings, values are any acceptable typeTo refer to a physical location, Open Transport uses the following structure:
{
"lat": 50.1,
"lng": 0.12
}
lat
- (number) Latitudelng
- (number) Longitude