Tekninen kuvaus Aineistopalauterajapinta

Versio 1.0

Rajapinta mahdollistaa vihjetiedon lähettämisen Maanmittauslaitoksen digitaalisissa paikkatietoaineistoissa olevista puutteista sovellus-sovellus yhteydellä.

Rajapintaversiot

Rajapinnasta on erikseen tuotanto- ja testausversio. Molemmat versiot toimivat asiakassovelluksen kannalta samalla tavalla, mutta testausversio ei tallenna / lähetä eteenpäin rajapinnan kautta lähetettyjä palautteita. Tätä voi siis käyttää asiakassovelluksen yhteensopivuuden varmistamiseen mm. XML-sanoman osalta.

Palvelun reunaehdot

  • Palvelu on normaalitilanteessa käytössä 24/7
  • Palvelun käyttöön ei tarvita tunnistautumista

Palautteen lähetys

Aineistopalaute lähetetään XML-viestinä HTTP/POST kutsuna SSL/TLS-salatun yhteyden yli.

Skeemakuvaus ja esimerkki XML-viestistä.

XML-tiedoston elementtien merkitys

Elementti/attribuutti Merkitys Pakollinen (P)/ Valinnainen (V)
LahetysHetki Palautteen lähetysaika ISO 8601 (xsd:dateTime) muodossa. P
MaastokohdeNimi Maastokohde, jota palaute koskee (esim. rakennus) P
KuvausTeksti Palautteen kuvaus (esim. laavu) V
SyyTeksti Palautteen syy (esim. uusi, poistunut) V
Sijainti/gml:Point/@srsName Sijaintitiedon koordinaatistotunnus EPSG-koodina. Tässä versiossa ainoastaan arvo EPSG:3067 (ETRS-TM35FIN -tasokoordinaatisto) on sallittu. P
Sijainti/gml:Point/gml:pos Palautteen kohteen koordinaatit. Järjestys itä (E) pohjoinen (N) P
Yhteystiedot/SahkopostiosoiteTeksti Palautteen antajan sähköpostiosoite. V
Yhteystiedot/PuhelinnumeroTeksti Palautteen antajan puhelinnumero. V

 

Paluuarvot

HTTP paluuarvo Merkitys
202 Accepted Palautteen käsittely suoritettiin onnistuneesti.
400 Bad Request Pyyntöviesti on sisällöltään virheellinen.
404 Not Found Palvelua ei löytynyt käytetystä yhteysosoitteesta.
405 Method Not Allowed HTTP-pyynnön metodia ei sallittu.
500 Internal Server Error Palautteen käsittelyssä tapahtui odottamaton virhe, pyyntöä ei voitu käsitellä.
502 Bad Gateway Yhteydessä taustapalveluun tapahtui virhe, pyyntöä ei voitu käsitellä.
505 Gateway Timed Out Aikakatkaisu lopetti pyynnön taustapalveluun, pyyntöä ei voitu käsitellä.

 

Esimerkki lähetyksestä

POST /api/aineistopalaute HTTP/1.1

Host: palveluosoite
Content-Type: application/xml
Content-Length: 883

 

<?xml version="1.0" encoding="UTF-8"?>
<ap:Aineistopalaute xmlns:ap="http://xml.nls.fi/Maasto/Palaute/2011/08/01"
xmlns:gml="http://www.opengis.net/gml"
xmlns:jhs="http://skeemat.jhs-suositukset.fi/yhteiset/2009/10/19"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xml.nls.fi/Maasto/Palaute/2011/08/01/aineistopalaute.xsd">
<ap:LahetysHetki>2011-05-03T14:32:18+02:00</ap:LahetysHetki>
<ap:MaastokohdeNimi>Rakennus</ap:MaastokohdeNimi>
<ap:KuvausTeksti>Laavu</ap:KuvausTeksti>
<ap:SyyTeksti>uusi</ap:SyyTeksti>
<ap:Sijainti>
<gml:Point srsName="EPSG:3067">
<gml:pos>406915.892 7195127.798</gml:pos>
</gml:Point>
</ap:Sijainti>
<ap:Yhteystiedot>
<jhs:SahkopostiosoiteTeksti>mikko.mittari@virasto.fi</jhs:SahkopostiosoiteTeksti>
<jhs:PuhelinnumeroTeksti>04012345678</jhs:PuhelinnumeroTeksti>
</ap:Yhteystiedot> </ap:Aineistopalaute>

 

Onnistuneen lähetyksen vastaus:

HTTP 202 Accepted
Date: Fri 12 Aug 2011 12:15:20 GMT
Content-Length: 2
Content-Type: text/plain; charset=utf-8

OK

 

Palvelun toimivuuden tarkistus

Palvelun toimivuuden voi haluttaessa erikseen tarkistaa tekemällä HTTP/GET pyynnön rajapintaosoitteeseen. Jos palvelu toimii, palauttaa tämä vastauksen HTTP 200 OK statuskoodilla. Virhetilanteessa pätevät samat statuskoodit kuin aineistopalautteen lähettämisessä. Tämän suorittaminen ei kuitenkaan ole tarpeen palautteiden lähettämisen yhteydessä.