Taivaanvahdin syöttörajapinta

Taivaanvahtiin voi lähettää havaintoja ja kommentteja joko XML- tai JSON-formaatissa. Palvelinpää vastaa kutsuihin siinä formaatissa jossa alkuperäinen viesti on lähetetty.
Havaintojen lähetyksestä yleisesti: Syöttörajapinta koostuu useista eri sanomatyypeistä:

Voit ladata kaikista sanomatyypeistä sanomaesimerkit tästä.

VersioURLMuutoksetKehittäjät
1 (2013-09-15) https://www.taivaanvahti.fi/apiAlkuperänen versio Mediasignal communications (design Emma Bruus)
2 (2021-09-24)https://www.taivaanvahti.fi/apiKielituellinen versioEmma Bruus

Katso myös havaintotieto- ja kommenttitietojen haku ja rajapinnan yleisohjeet.


Sanomien lähetyksestä ja logiikasta yleensä

Sanoman muoto ja lähetys

Sanoman lähetys

Rajapinta vastaanottaa sanomia HTTP POST metodilla. Yhteyden on oltava SSL-salattu. Rajapinnan kutsuosoitteen alussa on aina https://

Content type

Kun sanomaa lähetetään palvelimelle, tulee Content type olla asetettuna valitun lähetysformaatin mukaan. Nyt tuettuja content-type -määrityksiä ovat:

  • Content-type:application/json
  • Content-type:text/xml
Jos content typeä ei ole asetettu tai se on asetettu väärin, palauttaa rajapinta virheilmoituksen viestin muotoon liittyen.

Merkistö

Rajapinnan kautta lähetettävän materiaalin tulee käyttää utf-8 merkistöä. Jos syöte ei ole utf8:a palautetaan sanomasta virhe. XML- ja JSON tagit/elementit voidaan kutsuissa kirjoittaa joko isolla tai pienellä alkukirjaimella.

Source-kentän käyttö

Kaikkiin lähetettäviin sanomiin on hyvä liittää source-kenttä kuvaamaan sanoman lähdettä. Kenttä sisältää vapaamuotoisen tekstin, joka yksilöi viestin lähettämän sovelluksen. Voit valita kentän sisällön itse tai miettiä sitä yhdessä Taivaanvahdin ylläpidon kanssa.

Havaintoa lähetettäessä, muokattaessa tai kommentoitaessa lähdetieto on pakollinen. Ilman sitä järjestelmään ei tallennu mitään.

Esimerkkinä source-kentän lähetys osana XML-muotoista lomakkeenpyyntösanomaa:
<Request> <Source>MyClient</Source> <Action>FormTemplateRequest</Action> <Category>1</Category> </Request>

Lähetettävät tietotyypit

Päivämäärä

Päivämäärätietoja (Date) sisältävä sanoman sisätö tulee olla formaatissa YYYY-MM-DD. Päivä/date-tyyppisissä kentissä YYYY on vuosi (> 1900), MM kuukausi (1-12) ja DD päivä (1-31)

Aika

Aika (Time) ilmaistaan rajapinnassa muodossa: hh:mm:ss. hh=tunnit (00-23), mm=minuutit (00-59), ss=sekunnit (00-60). Esim. 20:48:00

Koordinaatit

Koordinaatit (Coodrinate)esitetään rajapinnassa aina desimaaliasteisina maantieteellisinä WGS84-koordinaattijärjestelmän mukaisesti. Tällöin koordinaatit tulevat puhtaasti numeerisina ja kelpaavat sellaisinaan mm. Googlen API:lle. GPS-kalikat antavat koordinaatit yleensä muodossa 64°23,123' (latitudi) 25°35,123' (longitudi), jossa asteiden jälkeen tulee kulmaminuutit (asteen 60-osia) desimaalilukun. GPS:n koordinaatit ovat WGS84-systeemissä, mutta muotoiluja voi olla vaikka kuinka monta. Mutta muunnos esitysformaatista rajapinnan hyväksymään formaattiin jää lähetyssoftan tekijän vastuulle. Koordinaattikenttä sisältää aina kaksi komponenttia latitudin (lat) ja longitudin (lon). Taivaanvahdin rajapinnassa komponentit syötetään latitudi ensin ja erotetaan toisistaan pilkulla. Esim: lat=64.23414, lon=20.13445.

Palvelimen vastausviestit ja virheidenkäsittelyn periaatteet

Palvelin vastaa sanomiin response-sanomalla, jonka sisällä oleva response_type -elementti kertoo onnistuiko operaatio vai ei. Jos operaatio onnistui, sisältää kenttä tekstin "Success". Jos operaatio epäonnistui, on response_type:ssä teksti "Error".

<?xml version="1.0"?> <response> <response_type>Success</response_type> <observation_id>150</observation_id> <observation_modification_key>abeab6df54ddf90ed9bb56cad26f4509</observation_modification_key> </response>

tai JSON-formaatissa:

{"response_type":"Success","observation_id":"1318","observation_modification_key":"dbe51b30bdcdb017226916357022446"}

Jos virhe pystytään kohdistamaan johonkin tiettyyn lähetettyyn kenttään, mainitaan kentän tunniste elementin field_id sisällä. Tämä antaa clientille mahdollisuuden esimerkiksi korostaa vastaavaa kenttää käyttöliittymässä ja näyttää response_message elementin sisältämä virheilmoitus käyttäjälle.

Esim: <?xml version="1.0"?> <response> <response_type>Error</response_type> <field_id>observation_date</field_id> <response_message> Päivä tulee esittää muodossa YYYY-MM-DD (2012-12-31). </response_message> </response>

Sanomat

Havaintolomakkeen kysely

Sanoman esimerkit: XML ja JSON
Vastauksen esimerkit: XML ja JSON

Tarkoitus

Koska erilaisten taivaanilmiöiden havainnot poikkeavat suuresti toisistaan ja muuttivat ajassa. Jokaisen uuden kentän tai mahdollisen syötearvon lisäys Taivaanvahtiin pitäisi jollain tavoin saada muutettua myös clientteihin. Koska matkapuhelinclienttejä on jo nyt olemassa useille käyttöjärjestelmille, olisi kovakoodattujen syötekenttien ylläpitäminen niille kaikille Taivaanvahdin puolesta mahdotonta.

Ratkaisuna problematiikkaan toteutettiin Taivaanvahtiin sovellus, joka tulostaa kuvauksen järjestelmän hyväksymästä havaintosisällöstä. Taivaanvahdin päälle kehitetyt clientit ovat tuettuja vain, jos ne noudattavat järjestelmän antamaa havaintojen syöttölomakkeiden sisältökuvausta.

Sisältö

Taivaanvahdin lomakkeen kuvauksen perusteella client pystyy itse luomaan käyttöliittymän, joka päivittyy automaattisesti järjestelmän muuttuessa. Lomakepohja (FormTemplate) listaa havaintolomakkeen kentät, tietotyypi, otsikot, mahdolliset arvojoukot ja ohjetekstit.

Havaintolomakepohjaa voidaan pyytää joko JSON- tai XML-formaatissa. Kyselyyn vastaava ohjelma tulostaa listan järjestelmän vastaanottamista havaintokategorioista, niille mahdollisista lisätiedoista, sekä havainnon perustiedoista. Lisätiedoista kuvataan kentän nimi, syötekentän tyyppi, sekä mahdolliset arvot (jos on).

Mahdolliset syötekentän tyypit ovat:
  • select: sisältää listan valittavista arvoista. Käyttäjä voi valita yhden.
  • checkbox: sisältää listan valittavista arvoista. Käyttäjä voi valita monta.
  • text: sisältää tiedon kuinka pitkä syöte on sallittu field_max_length -kentässä
  • numeric
  • date
  • time
  • coordinate

Lisäksi kukin lomakkeen syöte kenttä sisälyää tiedon siitä onko se havaintoa tehtäessä pakollinen. Jos field_mandatory -elementti sisältää arvon 1, on kyseessä havainnolle pakollinen tieto. Näin minimitoteutus havaintolomakkeesta voisi sisältää vain pakolliset kentät.

Havainnon lähetys

Havainnon tiedot on niputettu observation-elementtien sisään. Käytännössä tiedot koostuvat kenttien nimikoodeista (field_id) ja niiden arvoista (field_value). Jos kenttä on select tai checkbox tyyppinen, pitää field_value -kenttään kirjoittaa aina kentän arvon numeerinen id. Tekstikentien tapauksessa sisältö on vapaamuotoista.

Havainnon kieli annetaan rajapinnassa languages-elementteinä. Kenttään kirjoitetaan jokin Taivaanvahdin virallisesti tukemista kielikoodeista. Käytettävissä olevat kielikoodit saat getLanguagesRequest -kyselyllä.

Sanoman esimerkki:

<?xml version="1.0" encoding="UTF-8"?> <request> <action>ObservationAddRequest</action> <language>sv</language> <observation> <field> <field_id>observation_date</field_id> <field_value>2014-03-29</field_value> </field> <field> <field_id>observation_coordinates</field_id> <field_value>lat=61.44732,lon=23.85631</field_value> </field> <field> <field_id>observation_location</field_id> <field_value>Tampere</field_value> </field> <field> <field_id>user_name</field_id> <field_value>Etunimi Sukunimi</field_value> </field> <field> <field_id>user_email</field_id> <field_value>etunimi.sukunimi@domain.fi</field_value> </field> <field> <field_id>user_phone</field_id> <field_value>040-1234567</field_value> </field> <field> <field_id>observation_public</field_id> <field_value>1</field_value> </field> <field> <field_id>observation_description</field_id> <field_value>talipallo</field_value> </field> <field> <field_id>observation_user_team</field_id> <field_value>38</field_value> </field> <field> <field_id>observation_start_time</field_id> <field_value>10:20:36</field_value> </field> <field> <field_id>observation_end_time</field_id> <field_value>10:20:36</field_value> </field> <field> <field_id>specific_title_tulipallo</field_id> <field_value>954</field_value> </field> <field> <field_id>observation_request_opinion</field_id> <field_value>1</field_value> </field> <field> <field_id>specific_havaintoajan_tarkkuus</field_id> <field_value>564</field_value> </field> <field> <field_id>specific_lennon_kesto</field_id> <field_value>573</field_value> </field> <field> <field_id>specific_sammumistapa</field_id> <field_value>589</field_value> </field> <field> <field_id>specific_korkeus_katoamishetkellä</field_id> <field_value>602</field_value> </field> <field> <field_id>specific_tulipallon_ääni</field_id> <field_value>829</field_value> </field> <field> <field_id>category_id</field_id> <field_value>tulipallo</field_value> </field> </observation> <source>MyClient</source>

Kun havainto syötetään ensikertaa, ei sille ole olemassa havaintonumeroa järjestelmässä. Jos havainnon pakolliset kentät sanomassa on täytetty, se tallennetaan järjestelmään ja kutsun lähettäjälle palautetaan havainnon id ja muokkauksen oikeuttava koodi.

Kun havainnon tiedot on tallennettu onnistuneesti, palautetaan kutsuvalle taholle havainnon id ja muokkausavain vastaussanomassa:

<response> <response_type>Success</response_type> <observation_id>123</observation_id> <observation_modification_key> OY555OIK29B</observation_modification_key> </response>

Havainnon muokkaus

Sanoman esimerkit: XML ja JSON

Kun havaintoa muutetaan, tulee havainnon päivitettyjen tietojen lisäksi lähettää havainnon id ja muokkausavain. Ilman näitä tietoja havaintoa ei pysty muokkaamaan. Muutoin sanoman sisältö ja käsittely vastaa havainnon ensilähetystä. Ei-pakolliset kentät saavat puuttua sekä ensihavainnon että havaintomuutoksen syötteestä.

Havainnon poisto

Sanoman esimerkit: XML ja JSON
Havainnon voi poistaa lähettämällä seuraavan viestin palvelimelle.

<remove> <observation_id>32489</observation_id> <observation_modification_key>fblJHG776vhj</observation_modification_key> </remove> Palvelin vastaa poistopyyntöön joko:. <?xml version="1.0"?> <response> <response_type>Success</response_type> <observation_id>32489</observation_id> </response> tai esim. virheviestillä <?xml version="1.0"?> <response> <response_type>Error</response_type> <observation_id>32489</observation_id> <response_message>Havaintoa ei ole olemassa</response_message> </response>

Kuvan lähetys

Sanoman esimerkit: XML ja JSON

Kuvien lähetys tapahtuu tyypillisesti havainnon lähetyksen jälkeen. Rajapinta mahdollistaa kuitenkin kuvien lähetyksen havaintoon itsenäisesti, mikäli havainto on jo olemassa. Kuvan yhteydessä lähetetään havainnon tunniste, muokkausavain ja kuvan järjestysnumero havainnon sisällä. Jos numerolle on jo olemassa tallennettu kuva, vanha kuva korvataan uudella kuvalla. Kaikki kuvanlähetyssanoman kentät ovat pakollisia.

<Request> <Action>ObservationAddImageRequest</Action> <image> <observation_id>32489</observation_id> <observation_modification_key>fblJHG776vhj</observation_modification_key> <observation_image>1</observation_image> <image_name>Tuxuru13z.jpg</image_name> <mimetype>image/jpeg</mimetype> <encoding>Base64</encoding> <image_data>YAsvEYqewAGVYBsPMFsvQAImAAsPAMqusAIl4ZndsARIAAKGgBI2IAKWwAI14 EHV8AsPMAVZcAH2AAH2QErfIAH14AMmcCHl0AJGUBIGMBIV4Csu4AsvIArPFjJ44VAAAAiElE QVQYlV3OBw7CMBQDUFOnlE3ZUAhl773n/a9FAgWaWkq+9BJLH4jBYiiAsOMREI4JiSQjP/RIp TMGZHPMf8EtqNsu/iufUULZBFZQpVWrNwLwmmwJQ</image_data> </image> </Request> Mimetype-kenttä kertoo lähetettävän kuvan formaatin. Itse kuva lähetetään image_data -osiossa base64 enkoodattuna.

Kuvan poisto

Sanoman esimerkit: XML ja JSON
Havainnon kuvan voi poistaa lähettämällä seuraavan viestin palvelimelle.

<Request> <Action>ObservationRemoveImageRequest</Action> <remove> <observation_id>32489</observation_id> <observation_modification_key>fblJHG776vhj</observation_modification_key> <observation_image>1</observation_image> </remove> </Request> Palvelin vastaa poistopyyntöön joko:. <?xml version="1.0"?> <response> <response_type>Success</response_type> <observation_id>32489</observation_id> <observation_image>1</observation_image> </response> Tai: <?xml version="1.0"?> <response> <response_type>Error</response_type> <observation_id>32489</observation_id> <observation_image>1</observation_image> <response_message>Kuvaa ei ole olemassa</response_message> </response>

Kommentin lähetys

Sanoman esimerkit: XML ja JSON
Rajapinnan tulisi tukea kommenttien syöttöä havaintoihin. Kommentin lähetyssanomaan kuuluu kommentoitavan havainnon id, käyttäjän nimi, käyttäjän sähköpostiosoite ja itse kommenttiteksti. Mikäli client sisältää mahdollisuuden staattisesti asettaa käyttäjän nimen ja yhteystiedot, on havainnon kommentointi (ja lähetys) mahdollista toteuttaa todella vähällä näpyttelyllä.

<Request> <source>MyClient</source> <Action>ObservationAddCommentRequest</Action> <comment> <observation_id>3249</observation_id> <user_email>teppo.testaaja@kuukkeli.fi</user_email> <user_name>Teppo Testaajamäki</user_name> <comment_message>Loistokuva!</comment_message> </comment> </Request> Palvelin vastaa poistopyyntöön tallennuksen onnistuessa: <?xml version="1.0"?> <response> <response_type>Success</response_type> <observation_id>3249</observation_id> </response> Tai virheen sattuessa: <?xml version="1.0"?> <response> <response_type>Error</response_type> <observation_id>3249</observation_id> <response_message>Kommentin teksti puuttuu</response_message> </response>

Kommenttien poisto tai muokkaus ei tällä hetkellä ole käyttäjän ulottuvilla edes normitaivaanvahdissa. Siksi ominaisuudet eivät sisälly rajapintakuvaukseen.

Client-ohjelmoinnin yleislogiikka

Havaintolomakepohjien haku

Karu pseudokoodiesimerkki:

Connection connection = HttpsConnect('https://www.taivaanvahti.fi/api');

// Hae järjestelmän tukemat kielet

$languages = connection.HttpsGet('getLanguagesRequest/xml/');

// Valitse haluamasi käyttökieli
if( in_array( $device_language, $languages ){
	$ui_language = $device_language;
}

$FormCounter=1;

// Loopataan lomakkeet palvelimelta yksi kerrallaan,
// kunnes palvelin sanoo 'Ei oo lisää'

while ( $FormTemplateResponse != "Error"){

$FormTemplateResponse = connection.SendToServer("
	<Request>
	<Source>MyClient</Source>
	<Action>FormTemplateRequest</Action>
	<Category>$FormCounter</Category>
	<Language>$ui_language</language>
	</Request> 
	");

// Tallennetaan saadut tiedot 
if ($FormTemplateResponse != "Error"){
	saveTemplate( $FormTemplateResponse);
	generateTemplateUI( $FormTemplateResponse );
}else{
    doErrorHandling ( $FormTemplateResponse );
}

$FormCounter= $FormCounter+1;

}
Emma Bruus 2021-9