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ä.