≡ Sisukord

Stuudiumi API

Stuudiumi integreerimine õpiku-keskkondadega

Eesmärk

Stuudiumit kasutav õpetaja saaks oma õpilastega jagada mõnes välises keskkonnas (e-õpik, e-test, vms) asuvaid ressursse või teenuseid nii, et ei peaks eraldi tegelema õpilastele uute kasutajakontode loomise ja haldamisega.

Siin kirjeldatud integratsioon on kasutatav juhul, kui sinu keskkonnas saab õpetaja luua sisust komplekte/“päevikuid”, mis on seotud konkreetsete õpilaste hulkadega (õpilased, kes õpivad koos ühte õppeainet).

Üks Stuudiumi päevik saab olla seotud mitme erineva komplektiga, aga üks komplekt saab olla seotud vaid ühe Stuudiumi päevikuga. See tähendab, et kui õpetaja soovib oma kahe Stuudiumi päeviku (nt “6a matemaatika” ja “6b matemaatika”) õpilastega jagada sama õpikut/sisu/ülesandeid, peab ta sinu keskkonnas looma kaks komplekti.

Kui komplekt on Stuudiumiga seotud, võib kompkekti sisu sinu keskkonnas igal hetkel muutuda või täieneda — Stuudiumiga on seotud vaid komplekt tervikuna, mitte sinna kuuluvad üksikud sisu-objektid; kõikidel komplektiga seotud õpilastel on ligipääs kogu komplekti sisule.

(Näiteks: õppeaasta või kursuse alguses saab õpetaja siduda Stuudiumiga sinu keskkonna komplekti “10. klassi matemaatika”, kus on vaid sissejuhatav peatükk, aga aja jooksul lisab õpetaja komplekti uut sisu)

Kasutus-stsenaarium

Õpetaja avab Stuudiumis päeviku, mille õpilastele soovib välisesse keskkonda ligipääsu anda
Õpetaja valib "Seo päevikuga [keskkonna nimi]" (edaspidi näitena "Õpik")
Õpetaja suunatakse Õpikusse, andes kaasa (täpne meetod kirjeldatud allpool) andmed päeviku ja õpilaste kohta
Õpik saab saadud info alusel luua endale vajalikud kasutajakontod
Õpilased ja õpetaja saavad hiljem Õpikusse sisse logida ka otse Õpiku keskkonna kaudu, valides variandi "Logi sisse Stuudiumiga"
Stuudiumiga sisselogimisel antakse Õpikule kasutaja Stuudiumi ID, mille alusel saab sisse loginud kasutaja seostada eelnevalt loodud kontoga.

Tehnilise protsessi kokkuvõte

Õpetaja alustab Stuudiumi päevikust andmete jagamist
Õpetaja suunatakse välisesse keskkonda
Väline keskkond pärib Stuudiumi päeviku andmed
(Välises keskkonnas luuakse Stuudiumiga päevikuga seotud "komplekt")
Väline keskkond teavitab Stuudiumit loodud seosest, andes kaasa aadressi, kust Stuudiumi kasutajad loodud komplekti näevad.
Stuudium vastab aadressiga, kust välise keskkonna kasutajad näeksid vastavat Stuudiumi päevikut (nt “Tagasi Stuudiumi päevikusse” nupu loomise tarbeks)
Kui seos välises keskkonnas kustutatakse, teavitab väline keskkond sellest Stuudiumit.

Tehnilised detailid

1.

Õpetaja alustab Stuudiumist andmete jagamist (nupul klõpsates)

2.

Õpetaja suunatakse (eelnevalt kokku lepitud) aadressile (nt https://example.com/stuudium?token=1234567890)

3.

Väline keskkond esitab Stuudiumi APIle saadud token-it kasutades päringu: https://api.ope.ee/v1.1/data/journal?token=1234567890

Päring peab olema autenditud API päringute autentimine lehel kirjeldatud viisil

Tokenon kuni 100 tähemärgi pikkune string (a-zA-Z0-9._-)

GET /v1.1/data/journal?token=1234567890
Host: api.ope.ee
Authorization: Data v2 …

4.

Stuudium vastab päringule andmetega päeviku, õpetajate ja õpilaste kohta:

{
    "activation_token": "string väärtus päeviku seose aktiveerimiseks (vt punkt 5)",
    "current_user": { // kasutaja, kes "nuppu vajutas"
        "id": "kooli-tähis-1-1234", // kasutaja muutumatu Stuudiumi ID. Nii see kui kõik teised ID-d on kuni 50 tähemärgi pikkused string väärtused (võivad sisaldada märke: a-z, A-Z, 0-9, - (sidekriips), _ (alakriips)). Kõik ID-d on unikaalsed koolide-üleselt.
        "name_first": "Mart",
        "name_last": "Tamm"
    },
    "client": {
        "id": "kooli-tähis-1",
        "label": "Tallinna 156. Keskkool",
    },
    "id": "kooli-tähis-1-journal-789", // Õpilaste rühma ("klassipäeviku") muutumatu ID. Kuna päevikus võib õpilaste koosseis muutuda, saab selle alusel hiljem pärida aktuaalset õpilaste koosseisu ning vältida samast õpilaste rühmast duplikaat-rühmade loomist
    "label": "7a 7b Matemaatika", // Päeviku inimloetav nimi (sama, mida õpetaja Stuudiumis näeb. Seda saab vajadusel kasutada loodud "grupi" nimena
    "year": 2019, // päeviku õppeaasta. Õppeaasta number tähistab õppeaasta lõppu, ehk "2019" tähendab õppeaastat "2018/2019"
    "teachers": [ // Päeviku õpetajad (üks kuni mitu)
        // {kasutaja objektid samal kujul nagu eelnevalt näha olev "current_user"}
    ],
    "students": [
        {
            "id": "kooli-tähis-1-1235", // kasutaja muutumatu Stuudiumi ID
            "name_first": "Andres",
            "name_last": "T.",
            "group_label": "7a", // õpilase klassi inimloetav tähis. Võib olla tühi
        },
        {
            "id": "kooli-tähis-1-1236", // kasutaja muutumatu Stuudiumi ID
            "name_first": "Mari",
            "name_last": "P.",
            "group_label": "7b"
        }
    ]

}

5.

Et aktiveerida Stuudiumi ja välise keskkonna vaheline seos pärast päeviku andmete pärimist (punkt 4), tee (punktis 3 kirjeldatud viisil autenditud) POST päring:

https://api.ope.ee/v1.1/data/journal-link/JOURNAL_ID

Päringu sisu:

5.1

Seose aktiveerimine. Päringu POST body sisu on JSON formaadis:

{
    "action": "activate",
    "activation_token": "punktis-4-saadud-väärtus", // activation_token toimib vaid ühe korra. Kui oled seose aktiveerimise järel kustutanud, tuleb seose loomiseks protsessi uuesti alustada (punktist 1)
    "subscribe_to_updates": true, // true/false, // kas soovid punktis 7 kirjeldatud viisil saada teavitusi päeviku andmete muutumise kohta.
    "thirdparty_id": "seose muutumatu ja unikaalne ID sinu keskkonnas (kuni 100 tähemärgi pikkune string)", // Seda väärtust on vaja hiljem seose uuendamiseks (kui muutub thirdparty_url)
    "thirdparty_label": "Kasutajatele loetav 'inimkeeles' silt, näiteks 'Punane Õpik'", // Pikkusega kuni 50 tähemärki
    "thirdparty_url": "https:// aadress sinu keskkonnas, kuhu Stuudiumist kasutajaid suunata saab" // Kuni 200 tähemärki
}

5.2

Seose uuendamine. Et uuendada juba loodud seost (kui muutub thirdparty_url ja/või thirdparty_label ja/või või kui soovid muuta seose subscribe_to_updates väärtust), tee päring samale aadressile, POST sisuga:

{
    "action": "update",
    "subscribe_to_updates": true, // true/false,
    "thirdparty_id": "seose muutumatu ja unikaalne ID sinu keskkonnas (kuni 100 tähemärgi pikkune string)", // Eelnevalt saadetud seose ID, mille andmeid uuendatakse.
    "thirdparty_label": "Uus silt",
    "thirdparty_url": "https:// aadress sinu keskkonnas, kuhu Stuudiumist kasutajaid suunata saab"
}

Stuudiumi API vastus edukale 5.1 või 5.2 punktis kirjeldatud päringule on JSON formaadis:

{
    "status": "ok",
    "url": "https:// aadress, kuhu võid kasutaja oma keskkonnast suunata, et ta näeks seotud päevikut Stuudiumis."
}

5.3

Seose kustutamine. Loodud seose kustutamiseks (näiteks juhul, kui seotud üksus sinu keskkonnas kustutatakse või muul viisil mitteaktiivseks muutub, tee päring samale aadressile POST sisuga:

{
    "action": "delete",
    "thirdparty_id": "seose muutumatu ja unikaalne ID sinu keskkonnas (kuni 100 tähemärgi pikkune string)", // Eelnevalt saadetud seose ID
}

Stuudiumi API vastus edukale kustutamispäringule on JSON formaadis {"status":"ok"} (Content-Type: application/json; charset=utf-8)

6.

Väline keskkond saab hiljem vajadusel uuesti pärida päeviku infot, et automaatselt tuvastada lisandunud/eemaldatud õpilased ja õpetajad. Selleks tuleb teha päring aadressile https://api.ope.ee/v1.1/data/journal/JOURNAL_ID (JOURNAL_ID on eelnevalt saadud päeviku ID, ehk näiteks kooli-tähis-1-journal-789). See päring on võimalik vaid siis, kui seos on eelnevalt aktiveeritud punktis 5. kirjeldatud viisil (ja seos ei ole hiljem kustutatud.)

Päringu vastuse formaat on sama, mis ülal kirjeldatu, aga ei sisalda current_user ega activation_token parameetreid.

7.

Stuudium saab välist keskkonda ka jooksvalt teavitada muutunud päevikutest.

Kui muutub välise keskkonnaga seotud päeviku koosseis (õpilased või õpetajad), teeb Stuudium POST päringu eelnevalt kokku lepitud aadressile (nt https://api.example.com/hook/stuudium).

Päringu POST body sisuks on JSON formaadis info muutunud päevikute ID-dega. Seejärel saab väline keskkond Stuudiumist pärida muutunud päevikute andmeid (punkt 5).

Stuudiumi poolt tehtav päring:

POST /hook/stuudium HTTP/1.1
Host: api.example.com
Content-Type: application/json
Stuudium-Auth: Stuudium saadab rakendusele rakenduse enda võtmed päringu õigsuse kontrollimiseks. vaata selgitust “API päringute autentimine” alalehelt

{
    "action": "journal-updates",
    "data": {
        "journals": ["kooli-tähis-1-journal-789", "kooli-tähis-1-journal-790"] // muutunud päevikute ID-d
    }
}

NB! Sinu rakendus peab enne päringu sisu töötlemist kontrollima Stuudium-Auth päises oleva allkirja õigsust.

Vasta Stuudiumi saadetud päringule {"status":"ok"} (200 OK, Content-Type: application/json). Kui Stuudium ei saa status: ok vastust, võib Stuudium hiljem sama päringut uuesti korrata (kuni eduka vastuse saamiseni).

Kui su serveri poolt päringu töötlemine võib aega võtta, talleta saadud andmed, saada status: ok vastus, ning töötle saadud andmeid seejärel asünkroonselt. (Kui Stuudiumi saadetud päringule vastamine võtab liiga kaua aega, võib Stuudiumi API eeldada, et info ei jõudnud kohale, ja proovib hiljem sama infot uuesti saata.)

Kodutööde saatmine Stuudiumisse

Et lisada seotud päevikusse kodutöö, tee POST päring aadressile /v1.1/data/journal-assignment/JOURNAL_ID

Päring on autenditud punktis 3 kirjeldatud viisil.

Päringu sisu:

{
    "action": "create", // lisa kodutöö
    "thirdparty_id": "päeviku sidumisel eelnevalt saadetud ID",
    "targets": ["kooli-tähis-1-1235", "kooli-tähis-1-2222"] // õpilaste ID-d
    // või: "targets": ["*"] // kõik päeviku õpilased
    "assigned_by": "kooli-tähis-1-9999", // Õpetaja kasutaja ID, kes ülesande lisas.
    "assignment": {
        "description": "Ülesande sisu tekstina, HTML ei ole lubatud. Kasutada võib reavahesid jne (pikkus ei ole piiratud).",
        "url": "https://example.com/geograafia/ylesanne/123",
        // aadress, kust avaneb ülesanne nii õpilastele kui õpetajatele. Kodutöö link võiks olla võimalikult "ilus", selge ja lühike, kuna link on oma alg-kujul näha ka õpilastele ja õpetajatele.
        "deadline": "2017-05-31" // ülesande tähtaeg YYYY-MM-DD formaadis,
        "assignment_thirdparty_id": "ülesande muutumatu ja unikaalne ID sinu keskkonnas (kuni 100 tähemärgi pikkune string)"
    }
}

Stuudiumi API vastus päringule on JSON formaadis:

{
    "status": "ok",
    "id": "loodud-ülesande-ID-stuudiumis"
}

Kui kodutööd ei lisata, on vastuse sisu (400 Bad Request staatusega):

{
    "status": "error",
    "error_message": "Inimloetav veateade, mida näidata õpetajale, kes üritas kodutööd lisada. Näiteks: Pärast kl 16:00 ei saa enam järgmiseks koolipäevaks kodutöid lisada. Või: Päevikus ei ole veel ühtegi tundi; enne kodutöö määramist lisa Stuudiumis päevikusse tund."
    // selle sõnumi sisus võib olla ka https://* link, mille võiks automaatselt tuvastada ning klikitavaks muuta
}

Et kontrollida, kas valitud kuupäevaks saab kodutööd lisada (ilma, et kodutöö tegelikult lisataks), saada päring samas formaadis nagu lisamis-päring, aga "action": "validate" väärtusega. assignment_thirdparty_id väli ei ole validate päringu puhul kohustuslik (aga selle võib siiski saata).

Kui kodutöö lisamine on võimalik, on vastuseks "status": "ok". Vea puhul on vastus samasugune, nagu kodutöö lisamise ("action": "create") ebaõnnestumise puhul.

Kui saadad "action": "validate" päringuga ka assignment_thirdparty_id väärtuse, ja see kodutöö on juba eelnevalt lisatud, saadab API vastuseks eelnevalt lisatud kodutöö info, ehk:

{
    "status": "ok",
    "id": "eelnevalt-loodud-ülesande-ID-stuudiumis"
}

Lisatud kodutöö kustutamiseks tee POST päring aadressile /v1.1/data/journal-assignment/JOURNAL_ID

Päringu sisu:

{
    "action": "delete", // kustuta kodutöö
    "id": "eelnevalt-loodud-ülesande-ID-stuudiumis",
    "deleted_by": "kooli-tähis-1-9999" // Õpetaja kasutaja ID, kes ülesande kustutas.
}

Stuudiumi API vastus edukale kustutamispäringule: {"status":"ok"} (200 OK, Content-Type: application/json)

Aadressid kasutaja Stuudiumisse suunamiseks

Järgnevad aadressid ei vaja autentimist

Et suunata õpetaja või õpilane konkreetsesse päevikusse, teades päeviku ID-d, suuna ta aadressile: https://api.ope.ee/v1.1/public/redirect/journal/$JOURNAL_ID

Õpetaja puhul avaneb seda aadressi kasutades õpetaja tavapärane päeviku vaade, kust saab sisse kanda tunde, kodutöösid ja tagasisidet. Õpilane suunatakse lehele, kus on valitud päeviku kõik tunnid ja tagasiside. Tavaliselt on õigem õpilane suunata allpool kirjeldatud õpilase lehele
Et suunata kasutaja kooli Stuudiumi esilehele, teades kasutaja või kooli ID-d, suuna ta aadressile: https://api.ope.ee/v1.1/public/redirect/home/$ID

$ID võib olla kooli ID (nt “demo”) või kasutaja ID (nt “demo-123”)

See, mis on konkreetse kasutaja “Stuudiumi esilehe” sisu, sõltub kasutaja rollist ja õigustest. Näiteks õpetajale avaneb õpetaja päevikute loetelu, õpilasele ja lapsevanemale avaneb õpilase ülevaate-leht, administraatorile avaneb Stuudiumi haldamise leht.
Et suunata õpilane või lapsevanem õpilase lehele, teades kasutaja ID-d, suuna ta aadressile: https://api.ope.ee/v1.1/public/redirect/student/$USER_ID

Õpilase peaks tavaliselt suunama just õpilase lehele (avaneb õpilase tavapärane esileht, kus on kogu tagasiside ja kodutööd), mitte konkreetsesse päevikusse.

Stuudium

Stuudiumi abi

Stuudiumi API

Stuudiumi integreerimine õpiku-keskkondadega

Eesmärk

Kasutus-stsenaarium

Tehnilise protsessi kokkuvõte

Tehnilised detailid

1.

2.

3.

4.

5.

5.1

5.2

5.3

6.

7.

Kodutööde saatmine Stuudiumisse

Aadressid kasutaja Stuudiumisse suunamiseks