API Version: 0
This document describes the status quo of the API implementation for the OSTAR project and will be continuously changed as the server changes.
This API was specifically designed for mobile clients, which means that we tried to keep the amount of data flowing from the server to the client as small as possible. The interface is RESTful with some extensions described later on. Benefits of a RESTful API are that also complex application logic can be hidden behind a easy and slim interface. Moreover such an API works well with HTTP caches and proxy servers to lower the server load.
We tried to keep things as easy and as natural as possible. For example, one major
design goal was a human readable API that is easly understandable. For most parameters
there is a human readable, possibly very long, paramter name and a very short
abbreviation with at most 3 letters, e.g.
All API responses are JSON formatted and have the same structure. One can immediately
see whether an API request was successful by looking at the
StatusCode field. For a
comprehensive list of status codes and error situations see
The server does currently not distinguish between GET and POST parameters, but this behavior may change in the future.
The API keeps evolving and at some point a new major version will be released which probably breaks with the previous version. So the API version should be a major building block of the URL. In fact, the first section of the URL is devoted to the API version.
In the next section the controller is specified.
Every controller defines a set of actions and so the third and the last section of the URL defines which action should be executed. The action name does not have to be equal to the third part of the URL, rather it must be derivable from it. For example, if the third section is an integer number, then it is interpreted as an identifier which should be shown, thus the show action is executed. If the action part is empty than it defaults to the index action.
Additionally to the standard RESTful routes there is a multishow action that is meant to facilitate the work with large datasets. Imagine a user wants to cache all POIs locally, then the user would have to make hundreds or thousands of requests to the server. In such a situation the user needs some kind of bulk loading mechanism for large datasets. The multishow action is exactely designed for this issue. Most of the controllers define a multishow action which is an extension to the standard show action with the only difference that more than one resource can be fetched. For more details see the specification for each controller.
Even though the HTTP parameters are all just strings the API defines a bunch of data types and the server follows the specification rigorously. Note that the parameters need to be URL encoded if they are sent by a GET request, e.g the plus in the DATETIME type becomes %2B.
|INTEGER||Integer number||1; 2; 3|
|IDS||A list of comma separated integers||10,1,3|
|LANGUAGE||2 lower case letters||en; de; it|
|GEOLOCATION||WGS 84 (Longitude,Latitude,Altitude)||11.454,46.232,0|
|LINESTRING||GEOLOCATION GEOLOCATION …||11.454,46.232,0 11.454,46.232,0|
|DATETIME||RFC 3339 (with optional fraction)||2012–12–27T14:21:17+01:00|
|MD5_HASH||MD5 hash in hex notation||098f6bcd4621d373cade4e832627b4f6|
Currently the OStar server deals with just one (street) network, the network of Bolzano. However, in the future there will be a couple of networks, e.g. from Latsch and other cities.
Whenever necessary the API takes the parameter
network_id or abbreviated
which is an integer number and specifies on which network necessary calculations
network_id is optional, if no value is specified then it defaults to the
first network which is currently Bolzano. However, if a
network_id is specified
and does not exist in the database, then a INVALID_NETWORK_EXCEPTION
The server defines the following controllers: