Tracker-API

Translation in progress.

= Tracker API =

Rajapinta jolla Tracker komponentti lähettää sijaintitietoja palvelimelle.

Rajapinta toteutetaan HTTP POST komennoilla. Data siirretään JSON muodossa application/json.

Rajapinnassa käytetään ainoastaan ASCII -merkistöä. (Eli ääkköset on kiellettyjä).

Ideat ja kommentit: Keskustelu:API

Tapahtumasanoma
Sanoma jolla tracker ilmoittaa palvelimelle tapahtumasta. Tapahtuma voi olla säännöllisesti ilmoitettava sijainti.

POST sanoma URL:iin : /api/v1/events

Sanoman http headerit:


 * User-Agent: tässä kerrotaan firmware softan nimi + versio + lisämodulien nimet ja versiot. Samoin kuin selaimessa.
 * Host: jotta toimitaan virtuaalihostien kanssa
 * Content-Type: määritellään datan muoto application/json => json

Huom: Koordinaatit vastaanotetaan NMEA muodossa joka saadaan suoraan GPS:ltä, tietokannassa ja muissa rajapinnoissa käytetään asteita. Kaavat http://home.online.no/~sigurdhu/Deg_formats.htm

Sanoman kentät

Example messages: { "version": "1", "tracker_code": "490154203237518", "time": "2012-01-08T21:20:59.000", "latitude": 4916.46,N", "longitude": 12311.12,W", "mac": "123123132213123213" }

Another example (positional_accuracy is not an official parameter): { "accuracy":0.94,"altitude":10.798,"heading":0,"latitude":65.811840733333,"longitude":25.0158354,"mac":"b389674b1da4d3b87e9040e3e714be37416b20c7","positional_accuracy":2.16,"satellite_count":7,"session_code":"2013-05-25T18:45:57.000Z","speed":0,"time":"2013-05-25T18:51:36.000Z","tracker_code":"thauta","version":"1","vertical_accuracy":1.94 }

Shared Secret Authetication
Using authentication when sending messages is optional. Normally you should use authentication.

Shared secret is at most 64 characters long string consisting of characters A-Z, a-z and 0-9. Regexp [01-9a-zA-Z]{1,64}

Computing mac parameter:


 * 1) Generate string A from all parameers except from mac -parameter. Parameters name and value are separated with colon (:). Parameters are separated with pipe-character (|).
 * 2) * Parameters are handled in alphabetical order according to ASCII character set. Note that capital/uppercase letters are before lowercase letters.
 * 3) * All parameters are included, including extensions parameters (X- prefix).
 * 4) * MAC is computed without URL encoding.
 * 5) * HMAC SHA-1 digest is computed from string A. Digest is converted to a hexadecimal string using lowercase letters.

Example:

Shared secret: VerySecret1 Message: { "version": "1" "tracker_code": "490154203237518" "time": "2012-01-08T21:20:59.000" "latitude": "4916.46,N" "longitude": "12311.12,W" "X-alarm": "" "X-foobar": "123" }

First create string A A=X-alarm:|X-foobar:123|latitude:4916.46,N|longitude:12311.12,W|time:2012-01-08T21:20:59.000|tracker_code:490154203237518|version:1

Then compute HMAC-SHA-1 digest from string A hmac-sha1=070c2873b261ea2d07ec32e532d612a447537cfd

Add mac parameter as last parameter to message. Final message that can be sent is following: version: 1 tracker_code: 490154203237518 time: 2012-01-08T21:20:59.000 latitude: 4916.46,N longitude: 12311.12,W X-alarm: X-foobar: 123 mac: 070c2873b261ea2d07ec32e532d612a447537cfd

Palvelimen vastaukset
HTTP statuskoodit

Palvelin palauttaa 200 OK koodin mikäli sijaintiviesti on onnistuneesti käsitelty.

Virhetilanteita


 * 5xx ongelmat palvelimella
 * 400 Bad Request - sanomaa ei ymmärretty
 * 401 Unauthorized - autentikointi ei onnistunut

Tracker API:n laajentaminen sovelluskohtaisilla parametreilla
Rajapintaa voi laajentaa sovelluskohtaisilla parametreilla. Näiden parametrien nimi alkaa aina prefiksillä X-. Parametrien nimet käyttävät ASCII merkistöä. Rajapintaa tukevien sovellusten tulee vastaanottaa laajennusparametrit ne vaikka sovellus ei tukisikaan kyseistä laajennusparametria. Esim sovellus voi joko jättää laajennusparametrin huomiotta kokonaan tai tallentaa sen tietokantaan sellaisenaan. Esim RuuviTrackerServer tallentaa laajennusparametrit arvoineen suoraan tietokantaan.

Esim


 * X-special-value: 123
 * X-altitude: 42m
 * X-Atmospheric-pressure: 101.325

Tulevaisuuden parannukset
Versio 2:
 * tiedonsiirron salaus esimerkiksi AES-algoritmilla
 * tuki usealle sanomalle yhden HTTP requestin sisällä
 * palvelimen paluukoodi/header jolla palvelin kertoo että trackerin halutaan hakevan uusi konfiguraatiotiedosto
 * osoite josta tracker voi hakea konfigurointidatansa

Links

 * http://www.gpspassion.com/forumsen/topic.asp?TOPIC_ID=135468
 * http://www.gpsinformation.org/dale/nmea.htm
 * http://en.wikipedia.org/wiki/Dilution_of_precision_%28GPS%29
 * http://hash.online-convert.com/sha1-generator