Käytön rajapinnan käyttöohjeet ja REST-rajapinnan kuvaus
Yleistä
Käytön rajapinnan avulla voidaan käyttää Kansallisarkistossa säilytettyä digitaalista tietoaineistoa sekä näihin liittyviä kuvailevia kontekstimetatietoja.
Hallinnollisia edellytyksiä kuvataan tarkemmin Kansallisarkiston sähköisen arkistoinnin palvelun sivuilla: Siirron jälkeen | Kansallisarkisto.
Tässä ohjeessa ohjeistetaan käytön rajapintaan kytkeytymistä ja käytön rajapinnan käyttöä
Käyttö tapahtuu suomi.fi -palveluväylän avulla, josta on oma ohjeistuksensa
Sapan hallinnointiin siirretty säilytysvaiheen tietoaineisto voidaan jakaa käyttöön sarjatason (siirtoerän metatietotunnuksella muodostetun) datasettien avulla. Tiedon siirrossa hyödynnetään suomi.fi-palveluväylää. Kansallisarkisto vastaa pääsynhallinnassa siitä, että asiakasorganisaation liityntäpalvelimeen kytketty alijärjestelmä saa vain tälle alijärjestelmälle luvitetut tiedot käyttöönsä. Asioiva organisaatio hallitsee itse sitä, kenelle luovuttaa katseluoikeuden omaan aineistoonsa.
Datasetit
Datasetti on asiakkaalle määritelty aineistokokonaisuus, joka kertoo, mitä osia tietoaineistosta on saatavilla hakua ja jakelua varten. Yksi datasetti sisältää tietoaineiston alasarjat arkistoyksiköineen ja alayksiköineen.
Datasetin avulla aineistoa on mahdollista käyttää ja jalostaa omiin tarpeisiin sekä jakaa eteenpäin kolmansille osapuolille. Tietoa on mahdollista käyttää Sapan kautta tai ladata JSON-tiedostona. Datasettiä kuvaavan JSON-tiedoston voi ladata joko Sapan käyttöliittymän tai rajapinnan kautta. Siihen liittyvät tiedostot ovat käytettävissä rajapinnan kautta. Rajapinnan käyttö vaatii erillisen API-avaimen, jonka luominen sekä datasettien noutaminen vaatii rajapintasiirtäjän roolituksen Sapaan. Sen lisäksi Digitaalisen käytön palvelun tulee luvittaa datasetit valitu(i)lle henkilö(i)lle. API-avaimeni -näkymässä voit tarkastella käyttöösi luotuja datasettejä sekä halutessasi ladata niitä koneellesi.
Datasetillä on rajallinen, vuoden voimassaoloaika. Kansallisarkisto muistuttaa asiakasorganisaatiota datasetin vanhenemista ja tekee tarpeelliset toimenpiteet, jos voimassaoloa on perusteltua jatkaa.
Käyttöprosessikokonaisuus
Alla olevassa kuvassa esitetään käytön toiminnallinen prosessi:
Tässä ohjeessa ohjeistetaan, miten eri vaiheet etenevät ja kerrotaan tarkemmin käytettävissä olevista rajapinnan kohteista eli endpointeista ja niiden vaatimuksista.
Hallinnolliset asiat
Jäljempänä oletetaan, että on kytkeydytty suomi.fi-palveluväylään, käytön valmistelevat/hallinnolliset vaiheet on suoritettu ja hallinnollisissa valmisteluissa on päädytty rajapintakäyttöön. Hallinnollisissa vaiheissa on tullut jo selväksi mitä aineistoa rajapintojen kautta tullaan käyttämään.
Lisätietoja hallinnollisista prosesseista ja sopimuksista löydät Kansallisarkiston kotisivujen Ohjepankista: https://kansallisarkisto.fi/ohjepankki#sapa
Datasetin luominen
Kansallisarkisto luo datasetin, joka kattaa sovitun sarjan sekä halutut ilmentymätyypit. Kun datasetti on luotu, sille luvitettu henkilö saa sähköpostiin ilmoituksen tästä. Ilmoituksen jälkeen käyttäjä voi siirtyä Sapan käyttöliittymään hakemaan API-avainta.
API-avainten nouto
API-avainten nouto tapahtuu siirtokäyttöliittymässä. Edellytyksenä API-avaimen noutoon on se, että hallinnollisessa vaiheessa sinut on roolitettu siirtokäyttöliittymässä oikein Kansallisarkiston toimesta. Käytön rajapintojen kohdalla edellytyksenä on myös että käyttäjälle on luotu datasetti.
Datasetin viimeistely ja nouto
Kun datasetin käyttöä varten on luotu API-avain, tulee datasetti vielä viimeistellä Kansallisarkiston toimesta ennen kuin sen tietoja voi hakea käyttöliittymän tai rajapinnan kautta. Saat sähköposti-ilmoituksen kun datasetin viimeistely on tehty.
Datasetin käyttökappaleita haetaan käyttökappaleiden hakurajapinnalta. Aineisto on luvitettu aina sarjatasolle. Datasetin noutaminen edellyttää, että se on ensin luotu aiemman kohdan ohjeiden mukaisesti.
Käyttöliittymän kautta
Kirjaudu Sapan käyttöliittymään ja siirry sivulle API-avaimeni.
Paina Lataa dataset -painiketta. Tämä avaa datasetin tiedot uuteen välilehteen.
Tallenna datasetin tiedot.
Tallenna datasetin tiedot omaan järjestelmääsi.
Rajapinnan kautta
Ohjeet datasetin tietojen noutamiseen REST-rajapinnan kautta löydät alempaa REST-rajapintakuvauksen alta.
REST-rajapinnan kuvaus
Tässä osiossa esitellään datasettien noutamista rajapintojen kautta käytettäväksi omissa järjestelmissä
Ajantasainen REST-rajapinnan kuvaus OpenAPI-muodossa löytyy Suomi.fi-liityntäkatalogista.
Testi: Sähköisen arkistoinnin palvelu - ws - Testiliityntäkatalogi
Tuotanto: https://liityntakatalogi.suomi.fi/fi/dataset/sapa/resource/6711f33e-df99-490e-826b-3c7ccf3f7655
Datasetin sarjatason tietojen esittäminen → GET /api/latest/datasets/series/<document_id>
Toiminnon avulla esitetään yksittäisen datasetin aineiston sarjatason tiedot. Tämän toiminnon käyttäminen vaatii oikeudet hakea ja lukea omia datasettejä. Document_id on noudettavissa käyttöliittymästä API-avaimeni -sivulta.
Viestin määreet:
document_id – Datasetin yksilöivä tunniste SAPA-palvelussa.
Palautusviesti normaalitilanteissa:
HTTP 200 OK – Onnistunut viesti, palautuksena annetaan sarjatiedot haetusta datasetistä JSON-muodossa.
HTTP 400 Bad Request – Viesti ei tue parametrejä.
HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.
HTTP 404 Not Found – Datasettiä ei löytynyt.
HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin GET, PUT, tai DELETE).
Onnistuneen palautusviestin runko:
{
"data": {
"dataset_id": "1234567890"
"series": {
"content_level": "Alasarja"
"metadata" : {
"access_restrictions": {
"template_identifier": "100932679",
"authorizing_entity": "101498744"
},
"confidentiality_class": "Julkinen",
"content_category": "Viranomaisaineisto-arkistovaihe",
"content_dates_end": "2024-uu-uu",
"content_dates_start": "2024-uu-uu",
...
},
"volumes": {
"content_level": "Arkistoyksikkö",
"derivatives": [
{
"access_type": "diary_dump_hq",
"checksum": {
"algorithm": "md5",
"hash": "24d88f5e17e1ea4b0071ee341e44c99e"
},
"datetime": "2024-05-30T08:22:00.765000+00:00",
"download": "/api/latest/derivatives/objects/3602021692/download",
"filename": "0001.csv",
"filesize": 96176
},
...
],
"metadata": {
...
},
"subvolumes": {
"content_level": "Alayksikkö",
"derivatives": [
...
],
"metadata": {
...
}
}
}
}
},
"status": "success"
}Käyttökopion lataaminen → GET api/latest/derivatives/objects/<object_id>/download?<parameters>
Tällä toiminnolla voi ladata käyttökopion. Toiminnon käyttäminen vaatii oikeudet lukea käyttökopioita. Object_id on löydettävissä dataset-JSON-tiedostosta derivatives-osion alta.
Viestin määreet:
object_id – Käyttökopion tunniste.
<parameters> – Kyselyssä voi antaa seuraavat parametrit tulosjoukon suodattamista varten:
userid
Parametri, joka kertoo käyttäjän tunnisteen. Tunniste käytetään, kun tarkistetaan, onko käyttäjällä lupa käyttää kyseistä aineistoa.
usertype
Parametri, joka kertoo käyttäjätyypin, esimerkiksi Virtu-käyttäjä. Tyyppi käytetään, kun tarkistetaan, onko käyttäjällä lupa käyttää kyseistä aineistoa.
ip
Parametri, joka kertoo pyynnön IP-osoitteen. IP-osoite käytetään, kun tarkistetaan, onko lupa käyttää kyseistä aineistoa, kun aineiston luvitus vaatii luotettavan ympäristön käyttöä.
requestid
Astia-järjestelmän luoma tunniste, joka Astiassa yksilöi pyynnön.
Palautusviesti normaalitilanteissa:
HTTP 200 OK – Onnistunut viesti, palautuksena annetaan käyttökopio sellaisessa tiedostomuodossa kuin se on ilmoitettu. Tiedostomuoto ilmoitetaan viestin otsikossa content-type kentässä.
HTTP 400 Bad Request – Annettua parametria ei tueta.
HTTP 403 Forbidden – Pääsy käyttökopioon on estetty, käyttäjälle ei ole oikeuksia käyttökopioon.
HTTP 404 Not Found – Käyttökopiota ei löytynyt.
HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin GET).
HTTP 410 Gone – Käyttökopio on poistettu AHAA-palvelun metatiedoista.
HTTP 500 Internal Server Error – Ei saatu yhteyttä ulkoisiin palveluihin käyttörajoituksien ja käyttöoikeuksien tarkistamista varten.