Tekninen kuvaus Arkistoasiakirjojen kyselypalvelu (REST)

Yhteys palvelun ja asiakkaan välillä on SSL-suojattu (Secure Socket Layer, HTTPS-protokolla). Palveluun pitää kirjautua sisään antamalla käyttäjätunnus ja salasana. Käytössä on HTTP Basic Authentication -tunnistus, jonka on oltava mukana jokaisessa pyynnössä. Arkistoasiakirjojen kyselypalvelu (rest) kerää hakuihin liittyviä tilasto- ja laskutustietoja palvelupyyntöjen perusteella käyttäjätunnuksittain jaoteltuna.

Palvelu on käytettävissä ma - su klo 00.15 - 23.15.

Loppukäyttäjien lokitus

Arkistoasiakirjojen kyselypalvelun (REST) palvelinjärjestelmässä tallennetaan lokeihin tietoa myös asiakassovelluksessa tunnistetusta loppukäyttäjästä, mikäli asiakassovellus välittää rajapintapalvelulle loppukäyttäjää identifioivan tunnisteen kunkin rajapintapyynnön yhteydessä.

Teknisesti rajapintapalvelun kutsuissa tunniste tulee välittää HTTP-standardin mukaisena Request Header-kenttänä nimeltään "enduserid" ja jonka arvon tulee olla merkkijono (välilyönnit ei sallittuja, pituus max. 60 merkkiä). Muutoin merkkijonon sisältö voi olla asiakassovelluksen määrittämä, mutta kuitenkin siten, että tarvittaessa tunnisteen perusteella on selvitettävissä loppukäyttäjä asiakassovelluksen ylläpitäjän toimesta.

Yleistä lisätietoa HTTP:n Request Header-kentistä: https://developer.mozilla.org/en-US/docs/Glossary/Request_header

Lokitietojen siirron toimivuus on hyvä varmistaa ottamalla yhteyttä Maanmittauslaitokseen osoitteeseen verkkopalvelut@maanmittauslaitos.fi

Lisäksi lokitietoja tulee säilyttää kuuden vuoden ajan, jonka jälkeen ne tulee poistaa.

Aineistot ja tuotteet

Aineisto

Sähköisen arkiston aineisto karttuu suoraan toimitus- ja kirjaamistuotantojärjestelmistä sekä vanhaa paperiaineistoa digitoimalla. Sähköisessä arkistossa on keväällä 2017 noin 5,3 miljoonaa asiakirjaa ja 300 000 erillistä karttaa. Aineiston määrä kasvaa koko ajan.

Maanmittaustoimitusasiakirjat löytyvät sähköisestä arkistosta kattavasti vuodesta 1998 alkaen. Vanhempaa aineistoa sähköisestä arkistosta löytyy aina isojaosta, 1700-luvulta alkaen. Vanhaa aineistoa (vuotta 1998 vanhempaa) on digitoitu sähköiseen arkistoon tarveperusteisesti. Kaiken kaikkiaan MML:n koko paperisesta maanmittaustoimitusarkistosta on digitoitu arviolta 5 %. Arkistossa on n. 2,5 miljoonaa toimitusasiakirja- ja karttatiedostoa.

Kiinteistöjen kirjaamisasiakirjoja MML:n paperiarkistossa on vuodesta 1993 alkaen. Vanhemmat aineistot on luovutettu Arkistolaitokselle. Kirjaamisasiakirjat ovat kattavasti sähköisessä arkistossa vuoden 2013 toukokuusta alkaen. Vanhempaa aineistoa (1993-2013) digitoidaan sähköiseen arkistoon tarveperusteisesti. Kirjaamisasiakirjoja MML:n arkistossa on n. 2,5 miljoonaa.

Asiakirjat on järjestetty sähköiseen arkistoon maanmittaustoimitus- tai kirjaamisasiakohtaisesti. Yksi toimitus tai kirjaamisasia muodostaa yhden ns. arkistokansion sähköisessä arkistossa. Sähköisestä arkistosta löytyy arkistokansio kaikista MML:n paperiarkistoon arkistoiduista toimituksista ja kirjaamisasioista. Kansio löytyy vaikka aineistoa ei olisi digitoitu. Rajapinta palauttaa ensivaiheessa arkistokansion metatiedot sekä asiakirjojen kuvailutiedot, mikäli asiakirjat ovat sähköisessä arkistossa. Näiden tietojen perusteella käyttäjä voi valita, mitä asiakirjoja hän haluaa katsella.

Vanha arkistoaineisto on järjestetty sähköiseen arkistoon vanhan rekisteritiedon perusteella, jota ylläpidettiin vuosikymmenien kuluessa paikallisesti vaihtelevilla menettelyillä. Tämän vuoksi metatiedoissa on poikkeuksia, jotka voivat aiheuttaa epäonnistuneita hakuja, vaikka aineiston olisi sähköisessä arkistossa. Näissä tapauksissa käyttäjät voivat olla yhteydessä Maanmittauslaitoksen asiakaspalveluun.

Rajapinnan käyttö edellyttää Kiinteistötietojen kyselypalvelujen OGC API Features ja REST käyttöä. Rajapintaa kutsutaan arkistokansion arkistoviitteellä ja kuntakoodilla tai arkistokansion asianumerolla, jotka saadaan Kiinteistötietojen kyselypalveluista.

Palvelun skeemat

Tuote	Skeema
Arkistoasian ja asikirjojen metatiedot	http://xml.nls.fi/XML/Schema/sovellus/ARKKIrest/asiakasdokumentaatio/versionhallinta/1.0/Skeema/TietopalveluhaunTulos.xsd

Kyselyt ja esimerkit

Arkistoasian ja asiakirjojen metatiedot

XML-rakenne pyydetään palvelusta HTTPS/GET-protokollaan perustuvalla kyselyllä. Kyselyyn sisältyvät parametrit, joiden mukaista tietoa haetaan.

Hakuparametrit

Nimi	Aineisto	Esim.
Arkistoviite ja kuntakoodi	Maanmittaustoimitukset vuoden 2004 loppuun	Arkistoviitteen muoto voi vaihdella. Esim. 17:4 17 ISOJAKO 337-1 204:2001:1
Arkistoviite ja vakiotu kuntakoodi 999	Kirjaamisasiakirjat 4/2013 asti	esim. 715:2001:lh:2856
Arkistoviite	Maanmittaustoimituset 2005 alkaen	Vakioitu muoto esim. MMLm/949/33/2009
Arkistoviite	Kirjaamisasiat 5/2013 alkaen	Vakioitu muoto esim. MML/55569/70/2014

Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, arkistoviite: 337-1, kuntakoodi: 105.

https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=337-1&municipalityId=105

Esimerkkitiedosto vastauksesta

Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, arkistoviite: 17 ISOJAKO, kuntakoodi: 090

https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=17 ISOJAKO&municipalityId=090

Esimerkkitiedosto vastauksesta

Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, arkistoviite: 204:2001:1, kuntakoodi:204

https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=204:2001:1&municipalityId=204

Esimerkkitiedosto vastauksesta

Esimerkiksi kiinteistöjen kirjaamisasian ja asiakirjojen metatiedot, arkistoviite: 715:2001:lh:2856, vakioitu kuntakoodi: 999

https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=715:2001:lh:2856&municipalityId=999

Esimerkkitiedosto vastauksesta

Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, muodoltaan vakioitu arkistoviite: MMLm/949/33/2009

https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?nativeidentifier=MMLm/949/33/2009

Esimerkkitiedosto vastauksesta

Esimerkiksi kiinteistöjen kirjaamisasian ja asiakirjojen metatiedot, muodoltaan vakioitu arkistoviite: MML/55569/70/2014

https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?nativeidentifier=MML/55569/70/2014

Esimerkkitiedosto vastauksesta

Arkistoasiakirja

Arkistoasiakirja pyydetään palvelusta HTTPS/GET-protokollaan perustuvalla kyselyllä.

Hakuparametrit

Nimi	Aineisto	Esim
AsiakirjanNumero		30548387

Esimerkiksi arkistoasiakirja, ID-numero 6776693

https://arkkitp.nls.fi/ArkkiTP/v1/File?documentNumber=6776693

Versiohallinta

Arkistoasiakirjojen kyselypalvelu (REST) Versio 4.0, 12/2023

Arkistoasiakirjojen kyselypalvelu (REST) Versio 1.0, 3/2017

Virheiden hallinta

Palveluun kytkeytymiseen tai saatavuuteen sekä tietoliikenteeseen liittyvistä virhetilanteista palautetaan asiakassovellukselle virheilmoitus HTTP-virhekoodeina. Mm. seuraavat virhekoodit voivat tulla kyseeseen:

Virhekoodi	HTTP-tunnus	Selitys
400	Bad Request	Hakupyyntö tai sen parametrit ovat virheellisiä.
401	Unauthorized	Palvelu ei hyväksy asiakassovelluksen välittämää käyttäjätunnistetta.
403	Forbidden	Käyttäjälle ei ole oikeuksia tuotteeseen
500	Internal Server Error	Pyyntöä käsiteltäessä tapahtunut jokin odottamaton virhetilanne.
503	Service Unavailable	Palvelussa on liikaa ruuhkaa tai samalla käyttäjällä on liian monta samanaikaista pyyntöä.