UI-API

Translation in progress.

= UI API =

REST API which can be used by clients, such as web based map application, Android or iOS application can fetch data from the server.

API is implemented with JSON with JSONP extension.

A reasonable example of API is here

Common parameters for requests
These parameters can be used in all the request. If combination of the request and parameter is not sensible (e.g. request that returns at most single result and maxResults -parameter), the server will ignore the parameter.

JSONP
You can add parameter jsonp=XXX to every URL that generates a JSON response. This will make the response to use JSONP extension. For example http://some.domain.fi/api/v1/event/123?jsonp=mycallback.

Without -parameter:

{"foo": "bar", "baz": "quux"}

With  -parameter: mycallback({"foo": "bar", "baz": "quux"})

prettyPrint
All JSON generating URL:s support parameter prettyPrint=1, that causes the generated JSON to be "human readable". The default is not to pretty-print JSON.

maxResults
Parameter maxRequsts is used with requests that return several items (events, trackers). The parameter tells how many items the client wishes to receive at maximum. The server may return a smaller number of items.

Example
 * http://some.domain.fi/api/v1/trackers/2,13/events?maxResults=17

createTimeStart
Käytetään sanomissa jotka palauttavat listan tapahtumia. Parametrina aikaleima. Palauttaa vain tapahtumat, jotka on tallennettu annetun aikaleiman jälkeen palvelimen tietokantaan.

Aikaleima joko ISO 8601 muodossa tai Unix aikaleima

Esim:
 * http://some.domain.fi/api/v1/trackers/2/events?createTimeStart=2012-01-22T15:17:39.095+0000
 * http://some.domain.fi/api/v1/trackers/2/events?createTimeStart=915148801

TODO rename createTimeStart to storeTimeStart, probably clearer.

eventTimeStart
Käytetään sanomissa jotka palauttavat listan tapahtumia. Parametrina aikaleima. Palauttaa vain tapahtumat, joiden tapahtumaika on annetun aikaleiman jälkeen.

Aikaleima joko ISO 8601 muodossa tai Unix aikaleima

Esim:
 * http://some.domain.fi/api/v1/trackers/2/events?eventTimeStart=2012-01-22T15:17:39.095+0000
 * http://some.domain.fi/api/v1/trackers/2/events?eventTimeStart=915148801

Ping
Ping request can be uses to make a connection test.

GET /api/v1/ping

The server will respond in JSON format with protocol version, name and version of the server software and server timestamp.

For example: {"ruuvi-tracker-protocol-version":"1", "server-software":"CLJ-RTServer/0.0.1", "time": "2012-03-18T21:08:38.899+02:00"}

Get trackers
GET /api/v1/trackers GET /api/v1/trackers/
 * return all trackers
 * return trackers have given trackerIds

Hae tapahtumat
GET /api/v1/events/
 * EVENT_IDS is comma separated list of eventIds
 * /api/v1/events/1,231,212,32323
 * Hae tapahtumat joiden store time(= aika jolloin palvelin tallensi tapahtuman) on yhtäsuuri tai suurempi kuin  .
 * reitti-id (TODO)
 * Paluuarvona lista tapahtumia
 * id - tapahtuman tekninen tunniste (EVENT.id), huom arvo on merkkijono, ei numero.
 * tracker_id - TRACKER.id,, huom arvo on merkkijono, ei numero.
 * longitude, latitude
 * muut attribuutit, esim lämpötila, akun varaus jne, sovelluskohtaiset tiedot (X-athmospheric-pressure jne)
 * Käyttäjän tekemät kommentit event_annotations taulusta.
 * Tapautumassa ei välttämättä ole aina mukana sijaintitietoja

Get events related to trackers
GET /api/v1/trackers//events


 * TRACKER_IDS is comma separated list of trackers
 * E.g. http://domain.fi/api/v1/trackers/123,321,212/events returns events for trackers 123, 321 ja 212 respectively
 * events are returned oldest first
 * There is a limit on how many events are returned (typically 50)
 * Supported parameters
 * maxResults: only N results are returned at maximum
 * eventTimeStart: only events whose eventTime is equal or is after given timestamp are included
 * storeTimeStart: only events whose storeTime is equal or is after given timestamp are included
 * eventTimeEnd: only events whose eventTime is equal or is before given timestamp are included (NOT IMPLEMENTED YET)
 * storeTimeEnd: only events whose storeTime is equal or is before given timestamp are included (NOT IMPLEMENTED YET)

Get newest events related to a tracker (NOT IMPLEMENTED YET)
Similar to above.

GET /api/v1/trackers//events/latest


 * Returns N newest events accoring to eventTime

GET /api/v1/trackers//events/latestStored


 * Returns N newest events accoring to storeTime

Authentication
Authentication will be implemented with HTTP Basic authentication using username and password.

HTTP authentication is required to access private data. HTTP authentication is not required to see public data, but it is possible also access public data using authentication.