ePerusteet julkiset rajapinnat

Yleiset käytännöt

Rajapinnat on toteutettu ns. REST rajapintoina ja niissä käytetään JSON-kuvausta tietojen esittämiseen. Merkistökoodauksena käytetään UTF-8:ia.

Sisäiset tunnisteet:

Useimmissa objekteissa on kenttä "id" jonka arvo toimii objektin sisäisenä tunnisteena jota voi käyttää eperusteiden sisäisten viittausten selvittämiseen.

{
"id" : 611,
"nimi" : { "_id" : "552122", "fi" : "Audiovisuaalisen viestinnän perustutkinto", "sv" : "Grundexamen i audiovisuell kommunikation" },
...
}

id:llä tunnistetaan objektin tietty julkaistu versio ja se objektin tyypistä riippuen voi esiintyä myös rajapinnassa (esim. https://virkailija.opintopolku.fi/eperusteet-service/api/perusteet/611 ). Esim. perusteen tapauksessa tunniste ei ole pysyvä kahva tutkinnon perusteen uusimpaan versioon eikä sitä pidä käyttää viitteenä jos perusteeseen viitataan ulkoisesta järjestelmästä.

Viittaukset

Sisäiset viittaukset toisiin objekteihin on esitetty seuraavasti. Viittauksen arvona on kohdeobjektin tunniste (id). Huom! Arvo on merkkijono vaikka varsinaisen kohdeobjektin tunniste olisi tyypiltään luku.
?

Aikaleimat

AIkaleimat esitetään pääsääntöisesti millisekunteina alkaen 1970-01-01 00:00:00 UTC (ns. unix-timestamp millisekunteina).
?

Tekstien esittäminen (teksti)

?

Tekstit ovat pääsääntöisesti objekteja joissa sama sisältö voi olla tarjolla yhdellä tai useammalla kielellä.  Tekstiobjekteissa esiintyy kenttä "_id" joka muuttuu jos tekstin sisältö muuttuu.

Tekstisisällöt voivat olla ns. rikasta tekstiä jossa käytetään rajoitettua HTML-merkkausta. Sallitut merkkauselementit ovat:

p, strong ,em, s, ol, li, ul, blockquote, hr, pre, th, thead, a, abbr, table, caption, tbody, tr, td, th, thead, a, abbr

Edellä olevat vahvennetut elementit ovat tuettuja lähes kaikissa teksteissä. Taulukoita voi esiintyä lähinnä laajoissa tekstikappaleissa (perusteen sisältö -osuus). Taulukoita lukuun ottamatta elementeissä ei voi olla attribuutteja (esim. tyylimäärityksiä tms.).

Perusteen tiedot

Perusteen yleiset tiedot

Ammatillisen tutkinnon perusteen tiedot

-> Ammatillisen tutkinnon perusteen tiedot

Perusopetuksen perusteen tiedot

-> Perusopetuksen perusteen tiedot

REST-API

Swagger-dokumentaatio rajapinnasta: http://opetushallitus.github.io/eperusteet/api/eperusteet

Perusteiden haku

https://eperusteet.opintopolku.fi/eperusteet-service/api/external/perusteet

• palauttaa PagePerusteenJulkaistuData
  • perusteet listattuna content-tietueessa tietomallina PerusteenJulkaisuData

• yleiset ehdot:
  • Rajapinta on sivutettu; oletuksena palautetaan 10 tulosta
    • sivukokoa voi kontrolloida parametrilla "sivukoko"
    • sivun voi valita parametrilla "sivu"
• esimerkki vapaan sivistystyön voimassaolevat perusteet: https://eperusteet.opintopolku.fi/eperusteet-service/api/external/perusteet?koulutustyyppi=koulutustyyppi_10&voimassa=true

Yksittäisen perusteen julkaistujen tietojen haku

https://eperusteet.opintopolku.fi/eperusteet-service/api/external/peruste/{perusteId}

• palauttaa PerusteKaikkiDto
• esimerkki https://eperusteet.opintopolku.fi/eperusteet-service/api/external/peruste/8265240
• tarkemman tiedon saamiseksi rajapinnalle /perusteet/{perusteId} voi antaa perusteen rakenteen mukaisia sisältöviittauksia

  • esimerkiksi lukion peruste https://virkailija.testiopintopolku.fi/eperusteet-service/api/external/peruste/6828810 sisältää rakenteessaan lops2019 jonka sisältö löytyy oppiaineet

    "lops2019" : {
        "oppiaineet" : [ {
          "id" : 6828950,
          "nimi" : {
            "_id" : "6901378",
            "_tunniste" : "068ce193-4281-484d-8242-89c09d049750",
            "fi" : "Äidinkieli ja kirjallisuus",
            "sv" : "Modersmål och litteratur"
          },
    	  ...
        },
        ...
        ]
    }

  • lisäämällä rajapintaan /lops2019/oppiaineet: https://virkailija.testiopintopolku.fi/eperusteet-service/api/external/peruste/6828810/lops2019/oppiaineet saadaan listattua pelkästään kaikki oppiaineet

    [ {
          "id" : 6828950,
          "nimi" : {
            "_id" : "6901378",
            "_tunniste" : "068ce193-4281-484d-8242-89c09d049750",
            "fi" : "Äidinkieli ja kirjallisuus",
            "sv" : "Modersmål och litteratur"
          },
    	  ...
       },
       ...
    ]

  • lisäämällä rajapintaan tietueen id:n saadaan listattua yksittäisiä elementtejä /lops2019/oppiaineet/: https://virkailija.testiopintopolku.fi/eperusteet-service/api/external/peruste/6828810/lops2019/oppiaineet/6828950 saadaan listattua pelkästään kaikki oppiaineet

    {
        "id" : 6828950,
        "nimi" : {
            "_id" : "6901378",
            "_tunniste" : "068ce193-4281-484d-8242-89c09d049750",
            "fi" : "Äidinkieli ja kirjallisuus",
            "sv" : "Modersmål och litteratur"
        ...
    },

Huom! Alla olevaa rajapintakuvausta ei enää suositella julkisien tietojen hakuun.

Swagger-dokumentaatio rajapinnasta: https://eperusteet.opintopolku.fi/eperusteet-service/

Edellä kuvattu tietosisältö vastaa 'kaikki' rajapinnan palauttamaa tietoa. Muista rajapinnoissa palautettu tieto on suppeampaa.

Perusteiden haku ( https://eperusteet.opintopolku.fi/eperusteet-service/api/perusteet/ )

• Rajapinta on sivutettu; oletuksena palautetaan 25 tulosta

  • sivukokoa voi kontrolloida parametrilla "sivukoko"  (maksimi on 100 tulosta)

  • sivun voi valita parametrilla "sivu" (ensimmäinen sivu on "0")
    ?

    {     "data" : [{ perusteen tiedot suppeassa muodossa }, ...]     "sivuja" : 2,     "kokonaismäärä" : 41,     "sivukoko" : 25,     "sivu" : 0 }

• Rajapinnasta on mahdollisuus pyytää jonkin aikaleiman jälkeen muuttuneet tiedot (parametri muokattu; palauttaa perusteet joiden muokattu -aikaleima on suurempi kuin annettu aikaleima).
  • Esim: https://eperusteet.opintopolku.fi/eperusteet-service/api/perusteet?muokattu=1427438300557
• Tiedot palautetaan oletuksena valitun kielen mukaisesti aakkosjärjestyksessä perusteen nimen mukaan. Vaihtoehtoisesti hakutulokset voi järjestää muokkaushetken mukaan uusin ensin -järjestykseen:
  • https://eperusteet.opintopolku.fi/eperusteet-service/api/perusteet?jarjestys=muokattu

Esimerkki: perusopetuksen perusteen kaikkien tietojen haku

• Perusteen teknisen tunnisteen (id) löytää esim. koulutustyyppihaulla (koulutustyyppi_16 = perusopetus)
  • https://eperusteet.opintopolku.fi/eperusteet-service/api/perusteet?koulutustyyppi=koulutustyyppi_16
  • tai diaarinumerolla: https://eperusteet.opintopolku.fi/eperusteet-service/api/perusteet?diaarinumero=104/011/2014
• Hakutulosten perusteella selviää voimassa olevan version id (tätä kirjoitettaessa 419550) 
  
  • Koko peruste kaikkine tietoineen: https://eperusteet.opintopolku.fi/eperusteet-service/api/perusteet/419550/kaikki
  • Haun tuloksen voi laittaa välimuistiin; ehdollinen haku (If-Modified-Since, If-None-Match) on rajapinnassa tuettu.
    

Muutokset perusteisiin

Julkaistut perusteet voivat muuttua kahdella tapaa.

1. Olemassa olevaa perustetta korjataan. Tällöin peruste pysyy samana (ja esim. id ei muutu). Korjaus rajoittuu pieniin muutoksiin ja on tarkoitettu esim. kirjoitusvirheiden korjaamiseen tai puuttuvien käännösten lisäämiseen. Korjaus ei voi muuttaa perusteen rakennetta (esim. uusia tutkinnon osia ei julkaistuun perusteeseen voi lisätä).
2. Olemassa olevaan perusteeseen tehdään merkittävä muutos (esim. lisätään ammatilliseen perusteeseen tutkinnon osa). Tässä tapauksessa järjestelmään syntyy uusi peruste joka korvaa aikaisemman.
   
   • Uudella perusteella on uusi tunniste ja myös vanha versio jää järjestelmään.
   • Vanhan version voimassaolopäivämäärät päivittyvät uuden määräyksen tietojen mukaan.
   • Uudessa perusteessa on tieto (korvattavatDiaarinumerot) perusteista jotka uusi peruste korvaa.