OStar API Specification

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.

Table of Contents

General Remarks

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. language or l.

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 Status Codes.

The server does currently not distinguish between GET and POST parameters, but this behavior may change in the future.

Routing

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.

/<API_VERSION>/...

In the next section the controller is specified.

/<API_VERSION>/<CONTROLLER_NAME>

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.

Data Types

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.

Data Type Specification Example
BOOLEAN Boolean true; false
INTEGER Integer number 1; 2; 3
IDS A list of comma separated integers 10,1,3
STRING String foo; bar
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

Networks

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 nid which is an integer number and specifies on which network necessary calculations are based.

The 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 is returned.

Controllers

The server defines the following controllers:

  1. Categories
  2. Edges
  3. Images
  4. Networks
  5. Nodes
  6. Pois (Points of Interest)
  7. Schedules