Tälle sivulle on koostettu ohjeita Vardan järjestelmätoimittajille integraation rakentamista varten.
Aloittaessanne integraation rakentamista, olkaa yhteydessä Vardan asiakaspalveluun varda@opintopolku.fi käyttäjätunnusten toimitusta ja IP-avauksia varten.
Teknisissä kysymyksissä voitte olla yhteydessä kehittäjien asiakaspalveluun varda@csc.fi.
Tämän sivun sisältö:
Lisää aiheesta:
- Varhaiskasvatustietojen siirto
- Henkilöstötietojen siirto
- Lähdejärjestelmän ja tunnisteen käyttö
Vardan ympäristöt
Vardalle on kaksi ympäristöä: tuotanto- ja testiympäristö.
Tuotantoympäristö
Tuotantoympäristö löytyy osoitteesta https://backend.varda-db.csc.fi.
Testiympäristö
Testiympäristö löytyy osoitteesta https://backend-qa.varda-db.csc.fi. Testiympäristössä järjestelmätoimittaja voi vapaasti testata integraatiota. Ympäristö on kaikkien järjestelmätoimittajien yhteisessä käytössä.
Testiympäristön data alustetaan ajoittain anonymisoidulla tuotantodatalla. OPH ilmoittaa datantuonneista erikseen järjestelmätoimittajille.
Autentikointi
Rajapintakutsuja varten tarvitaan Opintopolku-tunnukset. Tunnuksien avulla haetaan API-token, joka toimitetaan kaikissa Vardan rajapintakutsuissa.
- API-token haetaan
/api/user/apikey/
-endpointista käyttäen basic-autentikaatiota- Yhdistä käyttäjätunnus ja salasana kaksoispisteellä (käyttäjätunnus:salasana) ja enkoodaa tämä merkkijono käyttäen base64-enkoodausta ISO-8859-1-merkistöllä
- Enkoodattu tunnus lähetetään Authorization-headerissä, esimerkiksi:
curl -X GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic htCyZREtdGVudGVyHXJvYr34OlI7O2hnQkp3JnM=' 'https://backend-qa.varda-db.csc.fi/api/user/apikey/'
API-token lähetetään seuraavissa rajapintakutsuissa Authorization-headerissä, esimerkiksi:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Token 5408c749948419625wb51212febb57h8f63k5231' -d '{}' 'https://backend-qa.varda-db.csc.fi/api/v1/henkilot/'
API-token vanhenee päivittäin 01.00-01.10 UTC+00:00 (03.00 Suomen aikaa), eli uusi token täytyy hakea joka päivä.
Jos API-token on vanhentunut, Varda palauttaa virhekoodin PE007 (lue lisää virhekoodeista täällä).
Rajapinnan dokumentaatio
Varda tarjoaa järjestelmätoimittajille REST-rajapinnan, joka käsittelee tietoa JSON-muodossa. Rajapinnan tarkka dokumentaatio on saatavilla Swagger-dokumentaationa. Dokumentaatiossa on kuvattu kaikki endpointit, niiden hyväksymät syötteet ja vastaukset:
- Julkinen Swagger-dokumentaatio löytyy osoitteesta https://virkailija.opintopolku.fi/varda/julkinen/swagger
- Interaktiivinen Swagger-dokumentaatio löytyy testiympäristöstä osoitteesta https://backend-qa.varda-db.csc.fi/varda/swagger/
- Testiympäristössä kirjaudutaan sisään Opintopolun käyttäjätunnuksella (Django Login → Kirjaudu sisään käyttäen Opintopolun tunnuksia), jonka jälkeen rajapintaa voi testata oikeilla kutsuilla
Lisäksi seuraavilta sivuilta löytyy ohjeita ja esimerkkejä yleisimpien rajapintojen käyttöön varhaiskasvatustietojen ja henkilöstötietojen tallennuksessa:
- Varhaiskasvatustiedot
- Henkilöstötiedot
- Lähdejärjestelmän ja tunnisteen käyttö
Rajapinnan rajoitukset
Rajapinnassa on rajoitettu kutsujen määrää käyttäjäkohtaisesti:
- 100 000 GET-kutsua päivässä
- 100 000 POST/PUT/PATCH/DELETE-kutsua päivässä
- 20 kutsua sekunnissa
Rajapinnan vastaukset
Rajapinnan vastaus riippuu käytetystä endpointista. Tarkat paluuviestit onnistuneessa kutsussa on kuvattu Swagger-dokumentaatiossa (lue Swagger-dokumentaatiosta täällä).
Statuskoodit
- Onnistuneet kutsut
- POST
- 201 normaalissa tapauksessa
- 200 henkilön/työntekijän/lapsen/tutkinnon luonnissa, jos vastaava objekti on jo olemassa (esimerkiksi lapsi syötetyllä varhaiskasvatuksen järjestäjällä ja henkilöllä on jo olemassa)
- PUT ja PATCH palauttaa statuskoodin 200
- DELETE palauttaa statuskoodin 204
- POST
- Epäonnistuneet kutsut
- 404, jos rajapintaa tai haettavaa objektia ei löydy
- 400, jos kutsun sisällössä on validointivirhe
- 403, jos käyttöoikeudet ovat puutteelliset
- 429, jos kutsuja on tehty yli rajoitusten sallima määrä (lue rajoituksista täällä)
- 500, jos kutsu on päättynyt sisäiseen virheeseen (ylläpito saa näistä ilmoituksen)
Virheviestit
Vardan virhetilanteissa rajapinnoista palautuvat virheet on kooditettu Opetushallituksen koodistopalvelussa. Koodistopalvelun avoimen rajapinnan kautta Vardan järjestelmätoimittajilla on mahdollisuus hakea Vardassa käytettävät koodistot lähdejärjestelmään. Virhekoodit ovat nähtävissä Vardan julkisella sivulla: https://virkailija.opintopolku.fi/varda/julkinen/koodistot/vardavirheviestit.
Rajapinnan palauttama virheviesti on JSON-objekti, joka koostuu virheellisistä kentistä ja niiden virheistä. Yksittäinen virhe sisältää virhekoodin, rajapinnan tuottaman kuvauksen ja selkokieliset käännökset. Esimerkiksi:
{
"tyosuhde_koodi": [
{
"error_code": "KO003",
"description": "Not a valid code.",
"translations": [
{
"language": "FI",
"description": "Koordiarvo on virheellinen."
}
]
}
],
"tyoaika_koodi": [
{
"error_code": "KO003",
"description": "Not a valid code.",
"translations": [
{
"language": "FI",
"description": "Koordiarvo on virheellinen."
}
]
}
]
}