Ohjeet järjestelmätoimittajille

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:

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
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/'
```

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:

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:

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.

Koodistot ja niiden mahdolliset arvot ovat nähtävillä Vardan julkisella sivulla: https://virkailija.opintopolku.fi/varda/julkinen/koodistot.

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

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."
        }
      ]
    }
  ]
}

Page tree