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ä. Tunnisteen välittäminen on vapaaehtoista.
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
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.
|
| 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öä. |