Page History

Tälle sivulle Tämän pääsivun alisivuille 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ö:

• Vardan ympäristöt
• Autentikointi
• Rajapinnan dokumentaatio
• Rajapinnan vastaukset

Lisää aiheesta:

.

Järjestelmätoimittajille suunnatun ohjekokonaisuuden sisältö:

• Integraation suunnittelu ja testaus
• Varhaiskasvatustietojen siirto
• Henkilöstötietojen siirto
• Lähdejärjestelmän ja tunnisteen käyttö
• Vardan

...

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.

1. API-token haetaan /api/user/apikey/-endpointista käyttäen basic-autentikaatiota
   1. 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ä
   2. 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/'

2. 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 (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:

• koodistot
• Tekninen vuosikello
• Testiympäristön datantuonnit

Vardan julkinen dokumentaatio:

• 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:

• Varhaiskasvatustietojen siirto
• Henkilöstötietojen siirto
• Lähdejärjestelmän ja tunnisteen käyttö

Vardan koodistot

Osa Vardan tietosisällön kentistä hyväksyy vain tietyn koodiston arvoja. Tällaisia kenttiä ovat esimerkiksi järjestämismuoto, tutkinto ja tehtävänimike.

...

• https://virkailija.opintopolku.fi/varda/julkinen/

...

Tietojen päivitys

Tietoja voi päivittää PUT- ja PATCH-kutsuilla. Vain tiettyjä kenttiä on mahdollista muokata. Vardan tietoluettelossa on kuvattu muokattavat kentät.

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 (lisää 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
• Epäonnistuneet kutsut
  • 404, jos rajapintaa tai haettavaa objektia ei löydy
  • 400, jos kutsun sisällössä on validointivirhe (lisää virheviesteistä täällä)
  • 403, jos käyttöoikeudet ovat puutteelliset
  • 429, jos kutsuja on tehty yli rajoitusten sallima määrä (lisää rajoituksista täällä)
  • 500, jos kutsu on päättynyt sisäiseen virheeseen (ylläpito saa näistä ilmoituksen)

Virheviestit

...

• tietomalli
• https://virkailija.opintopolku.fi/varda/julkinen/koodistot

...

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:

...

Vardan määräys ja tietoluettelo löytyvät sivulta:

• Määräykset ja ohjeet