eperusteet julkiset rajapinnat

Transkriptio

1 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:i a. 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. u.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. "_tutkinnonosa" : "637" Aikaleimat AIkaleimat esitetään pääsääntöisesti millisekunteina alkaen :00:00 UTC (ns. unix-timestamp millisekunteina). "voimassaoloalkaa" : Tekstien esittäminen (teksti) "nimi" : { "_id" : "193255", "fi" : "Matemaattis-luonnontieteellinen osaaminen", "sv" : "Kunnande i matematik och naturvetenskap" 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.).

2 Perusteen tiedot Perusteen yleiset tiedot kenttä tietotyyppi kuvaus id luku tunniste nimi teksti perusteen nimi koulutustyyppi <koodisto-uri> Koulutustyyppi; arvo koulutukset [ koulutus ] (vain ammatillisissa perusteissa). Tutkinnot jotka peruste määrittelee. kielet [merkkijono] Kielet joilla perusteen sisältö on olemassa. kuvaus teksti Perusteen tiivistelmä (ei ole osa varsinaista perustetekstiä) diaarinumero merkkijono Määräyksen diaarinumero voimassaoloalkaa aikaleima Perusteen voimassaolon alku (voimassaoloalkaa < voimassaololoppuu <= siirtymapaattyy) voimassaololoppuu aikaleima Perusteen voimassaolon loppu (voi olla tyhjä jos peruste on toistaiseksi voimassa) siirtymapaattyy aikaleima Perusteen siirtymäajan loppu (tyhjä jos peruste on toistaiseksi voimassa. Voi olla sama kuin voimassaololoppuu jos perusteella ei ole siirtymäaikaa. muokattu aikaleima perusteen viimeisin muokkaushetki tila merkkijono "valmis" jos kyseessä on julkaistu peruste tyyppi - - korvattavatdiaarinumerot [merkkijono] lista määräysten diaarinumeroita jotka tämä peruste korvaa. Voi viitata myös perusteeseen jota ei löydy järjestelmästä. osaamisalat [ osaamisala ] (vain ammatillisissa perusteissa) Tutkinnon osaamisalat tutkintonimikkeet [tutkintonimik e] (vain ammitillisissa perusteissa) Tutkinnon nimikkeet osaamisaloittain suoritustavat [ suoritustapa ] tutkinnonosat [ tutkinnonosa ] (vain ammatillisissa perusteissa) Tutkinnon suoritustavat (näyttötutkinto ja/tai opetussuunnitelmaperusteinen) (vain ammatillisissa perusteissa) Ammatillisen tutkinnon perusteen tiedot --> Ammatillisen tutkinnon perusteen tiedot Perusopetuksen perusteen tiedot --> Perusopetuksen opetussuunnitelman peruste REST-API Swagger-dokumentaatio rajapinnasta: Edellä kuvattu tietosisältö vastaa 'kaikki' rajapinnan palauttamaa tietoa. Muista rajapinnoissa palautettu tieto on suppeampaa. Perusteiden haku ( ) Rajapinta on sivutettu; oletuksena palautetaan 25 tulosta sivukokoa voi kontrolloida parametrilla "sivukoko" (maksimi on 100 tulosta)

3 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 suurempikuin annettu aikaleima). Esim: Tiedot palautetaan oletuksena valitun kielen mukaisesti aakkosjärjestyksessä perusteen nimen mukaan. Vaihtoehtoisesti hakutulokset voi järjestää muokkaushetken mukaan uusin ensin -järjestykseen: Esimerkki: perusopetuksen perusteen kaikkien tietojen haku Perusteen teknisen tunnisteen (id) löytää esim. koulutustyyppihaulla (koulutustyyppi_16 = perusopetus) tai diaarinumerolla: Hakutulosten perusteella selviää voimassa olevan version id (tätä kirjoitettaessa ) Koko peruste kaikkine tietoineen: 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 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ä). 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. eperusteet AMOSAA Resurssi Generoitu rajapintadokumentaatio API:n juuri Osoite Koulutuksen järjestäjän tietojen hakeminen Koulutuksen järjestäjän perustiedot organisaation oidilla: julkinen/koulutustoimijat/org/<oid> Kolmannen osapuolen näkökulmasta relevantit tiedot koulutuksen järjestäjästä Koulutuksen järjestäjän ID TODO: Ystäväorganisaatiot

4 Opetussuunnitelmien tietojen hakeminen Terminä opetussuunnitelma voi tarkoittaa pohjaa, yhteistä osaa, opetussuunnitelmaa tai opetussuunnitelmien kesken jaettua opetussuunnitelmaa. Kaikki opetussuunnitelmat ovat rakenteellisesti identtisiä, mutta sallitut sisältöelementit luonnissa on rajattu opetussuunnitelman tyypin mukaan. Esimerkiksi pohjat ja yhteiset osat sallivat ainoastaan tekstikappaleet. Pohjaa (tyyppi "pohja") ei ladata julkisesti vaan sen sisältö kopioidaan yhteisen osan pohjaksi sitä luotaessa Yhteinen osa (tyyppi "yhteinen") sisältää koulutuksen järjestäjään itseensä liittyviä asioita. Näitä on käytännössä ainoastaan yksi koulutuksen järjestäjällä. Useiden yhteisten osien luominen on työkalussa sallittu käytännön vuoksi. Opetussuunnitelma (tyyppi "ops") pohjautuu aina johonkin konkreettiseen perusteeseen Koulutuksen järjestäjällä on näitä useita Usean opetussuunnitelman luominen saman perusteen pohjalta on sallittu Opetussuunnitelmaa luotaessa perustepalvelun peruste ladataan amosaa palveluun jos sitä ei järjestelmässä ole tai se on muuttunut. Tämän ansiosta opetussuunnitelmalla on pohjana aina versio perusteesta joka sen luontihetkellä oli käytössä. Opetussuunnitelmien kesken jaettu opetussuunnitelma (tyyppi "yleinen") sisältää kaikille opetussuunnitelmille yhteistä sisältöä Pohjana käytetään perustepalvelussa luotua tutkinnon osien koosteperustetta (ei ole oikea peruste ja on piilotettu) jonka sisältö on kaikille yhteistä Tämä voi sisältää tutkinnon osia perusteista joita ei ole käytetty järjestelmässä muissa opetussuunnitelmissa Näitä voi olla muutamia, todennäköisimmin 0-3 koulutuksen järjestäjällä Opetussuunnitelmien hakeminen Julkaistujen opetussuunnitelmien lataaminen: julkinen/koulutustoimijat/<id>/opetussuunnitelmat Opetussuunnitelman perusteen tietojen lataaminen: perusteet/<perusteen id> Perusteen id tässä tapauksessa amosaa:n peruste id joka eroaa perustepalvelun perusteen id:stä! Opetussuunnitelman sisällöt Sisällön rakenteen hierarkia: julkinen/koulutustoimijat/{ktid/opetussuunnitelmat/<opsid>/otsikot Sisältöjen rakenteesta voi lukea enemmän täältä Yksittäinen sisältö: julkinen/koulutustoimijat/<ktid>/opetussuunnitelmat/<opsid>/tekstit/<sisältöviitteen id> Tutkinnon osien hakeminen Tutkinnon osien hakeminen koulutuksen järjestäjän kontekstissa: julkinen/koulutustoimijat/<id>/koodi/<koodi> Tutkinnon osien (kooditettujen sisältöelementtien) hakeminen pelkällä koodilla: julkinen/koodi/<koodi> Perusteen tutkinnon osaan pohjautuvan tutkinnon osan hakeminen: perusteet/<perusteen id>/tutkinnonosat/<perusteen tutkinnon osan id> Rajapinta palauttaa listan kaikista sijainneista missä koodia vastaava sisältö on määritetty. Tutkinnon osan paikallinen toteutus voidaan määrittää eri opetussuunnitelmien kontekstissa. Yrityksessä toimiminen voi tarkoittaa jotain ihan muuta auto- tai sirkusalalla. Tässä kontekstissa koodi voi olla muotoa tutkinnonosat_<numero> (Koodisto palvelun koodi) paikallinen_tutkinnonosa_<koulutuksen järjestäjän oid>_<tutkinnon osan koodi> (paikallinen koodi) Tutkinnon osan koodi on koulutuksen järjestäjän tasolla uniikki numero (Käytännössä ) Näistä saatavalla sijaintitiedolla (opetussuunnitelma ja tutkinnon osan id) voidaan ladata konkreettinen sisältöelementti: Sisältö: koulutustoimijat/<koulutuksen järjestäjän id>/opetussuunnitelmat/<opetussuunnitelman id>/tekstit/<tutkinnon osan id> Suorituspolkujen hakeminen Suorituspolulla tarkoitetaan perusteen muodostumispuun erikoistamista. Muodostumispuusta pystytään paikallisesti tiputtaa pois sisältöä siten, että perusteen muodostumispuun muodostumissäännöstö täyttyy. Suorituspolkuun pystytään myös liittämään paikallisia tutkinnon osia koodin tarkkuudella. Suorituspolkuja esittäessä on ladattava pohjalle ensin perusteen puurakenne. Muodostumispuu on rekursiivinen tietorakenne mikä koostuu solmuista joilla on yksilöivä tunniste-kenttä. Suorituspolku on assosiatiivinen säiliö, johon on lisätty tunniste kohtainen paikallinen sisältö. Jos tunnistetta vastaavaa sisältöä ei suorituspolusta löydy niin siihen ei ole paikallisesti otettu kantaa -> käytetään perusteen muodostumispuun toteutusta. Käytännössä suorituspolun esittämisessä piirretään muodostumispuuta rekursiivisesti ja indeksoidaan suorituspolkua jokaisen solmun tunnisteella ja päätetään siitä löytyvän sisällön avulla mitä tehdään. AMOSAA-työkalu varmistaa, että suorituspolku on validi viimeistään julkaisun yhteydessä.

5 Perusteen muodostumisen hakeminen Muodostuminen (sisältää muodostumispuun ja muun tarvittavan): perusteet/<perusteen id>/suoritustavat/<suoritustavan nimi> Suorituspolun paikallisen sisällön hakeminen Suorituspolku ladataan samalla tavalla kuin muut opetussuunnitelman sisällöt.