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