Stuudiumi API

• Üldinfo
• API päringute autentimine
• Kasutajate tuvastamine
• → Andmete pärimine
• Sidumine päevikute/õppetööga
• Jagamislink Uus

---

Stuudiumi API kaudu andmete pärimine

Andme-API kasutamiseks vajad CLIENT_ID ja CLIENT_SECRET võtmeid. Võtmeid saad kasutada API päringute autentimine lehel kirjeldatud viisil.

---

Päringud

Kõikide päringute aadressi alguseks on https://api.ope.ee/v1.1/data/

Päring: profiili lisaväljadega kasutajate pärimine

Päringu aadress: users/list/?client=KOOLI_ID&custom_field=LISAVÄLJA_ID

Näidispäring: https://api.ope.ee/v1.1/data/users/list/?client=demo&custom_field=access_chip_expiration, kus "demo" on kooli Stuudiumi aadressi algus (demo.ope.ee), ja "access_chip_expiration" on eelnevalt kooli jaoks seadistatud profiili lisaväli (näiteks kiipkaardi aegumise kuupäev).

Päringu vastuse formaat (JSON):

{
"users": [
    {
        "id": "demo-123", // kasutaja ID
        "name_first": "Inimese",
        "name_last": "Nimi",
        "email": "meil@example.com",
        "custom_fields": {
            "access_chip_expiration": "2016-03-04"
        }
    },
    {
        "name_first": "Teise Inimese",
        "name_last": "Nimi",
        "email": "meil-2@example.com",
        "custom_fields": {
            "access_chip_expiration": "2017-09-03"
        }
    }
]
}

Päring: õpilaste ja lapsevanemate nimekiri

Päringu aadress: users/list/?client=KOOLI_ID&type=students-parents

Näidispäring: https://api.ope.ee/v1.1/data/users/list/?client=demo&type=students-parents

Päringu vastuse formaat (JSON):

{
"users": [
    {
        "id": "demo-123", // kasutaja ID,
        "group": {
            "name": "1a"
        },
        "name_first": "Õpilase",
        "name_last": "Nimi",
        "idcode": "31111111111",
        "email": "meil@example.com",
        "address": "Tänav 1-1, 10001, Tallinn",
        "parents": [ // Õpilase lapsevanemad
            {
                "id": "demo-1231",
                "name_first": "Lapsevanema",
                "name_last": "Nimi",
                "address": "Tänav 1-1, 10001, Tallinn",
                "email": "meil2@example.com",
                "idcode": "31111111112",
                "telephone": "56 123 123"
            },
            {
                "id": "demo-1231",
                "name_first": "Teise Lapsevanema",
                "name_last": "Nimi",
                "address": "Tänav 1-1, 10001, Tallinn",
                "email": "meil3@example.com",
                "idcode": "31111111113",
                "telephone": null
            }
        ]
    },
    {
        "id": "demo-124",
        "name_first": "Teise Lapse",
        "name_last": "Nimi",
        ....
    }
]
}

---

Päring: päevikute ja päevikute õpetajate ning õpilaste loetelu

Päringu aadress: journals/list/?client=KOOLI_ID&with_students=1

Näidispäring: https://api.ope.ee/v1.1/data/journals/list/?client=demo&with_students=1, kus "demo" on kooli Stuudiumi aadressi algus (demo.ope.ee).

NB! with_students=1 parameeter on kohustuslik.

Päringu vastuse formaat (JSON):

{
"year": 2016, // õppeaasta. (2016 tähendab õppeaastat 2015/2016)
"journals": [ // päevikud
    {
        "id": "päeviku-muutumatu-ID",
        "subject": "Eesti keel",
        "groups": ["10a", "10b"], // Päevikuga seotud klass(id)
        "teachers": [
            {
                "id": "demo-123", // kasutaja muutumatu ID
                "name_first": "Õpetaja",
                "name_last": "Nimi"
            },
            {
                "id": "demo-124",
                "name_first": "Teise Õpetaja",
                "name_last": "Nimi"
            }
        ],
        "students": [
            {
                "id": "demo-125",
                "name_first": "Õpilase",
                "name_last": "Nimi",
                "idcode": "12345678901", // võib olla ka tühi
            },
            {
                "id": "demo-126",
                "name_first": "Teise Õpilase",
                "name_last": "Nimi",
                "idcode": "12345678901",
            }
        ]
    },
    {
        // teine päevik sama struktuuriga
    },
    {
        // kolmas jne päevik sama struktuuriga
    }
]
}

---

Päring: Nõusolekud andmete jagamiseks

Päringu aadress data/consents/$TÜÜP. $TÜÜP väärtus on string, mille saad rakenduse registreerimisel Stuudiumilt. Nt: test-n6usolek.

Näidispäring https://api.ope.ee/v1.1/data/consents/test-n6usolek

Päringu vastuse formaat (JSON):

[
{
    "client_id":"demo1",
    "client_name":"Demo Kool",
    "last_updated_at":"2016-12-09T15:00:09+02:00", // millal viimati andmeid uuendati. Kui viimane päring oli hiljem kui see kuupäev, ei ole vaja täielikke andmeid uuesti pärida, kuna need ei ole muutunud.
    "url":"https:\/\/api.ope.ee\/v1.1\/data\/consents\/test-n6usolek?client=demo1" // aadress, kust saab pärida selle kooli täieliku nõusolekute nimekirja
},
{
    "client_id":"demo2",
    "client_name":"Teine Demo Kool",
    "last_updated_at":"2016-12-09T15:00:09+02:00",
    "url":"https:\/\/api.ope.ee\/v1.1\/data\/consents\/test-n6usolek?client=demo2"
}
]

Ühe kooli nõusolekute täieliku nimekirja saamiseks tee päring vastava kooli url aadressile.

Kooli nõusolekute päringu vastuse formaat (JSON):

[
{
    "id":"demo1-121", // selle kasutaja (õpilase) muutumatu ID Stuudiumis (ehk siis: kui "id" on sama, aga muutunud on nimi ja/või isikukood, on siiski tegu sama isikuga)
    "name_first":"Lapse", // teoorias võib ees ja/või perenimi olla tühi (andmeid haldab iga kool ise). Tühja nimega kasutajate andmeid võib vajadusel töötlemisel ignoreerida
    "name_last":"Perenimi",
    "idcode":"60412345678", // võib olla tühi
    "consents": [ // vastused nõusolekute-küsimustele selle kasutaja jaoks
        {
            "type": "alamtyyp-yks", // nõusoleku (alam)tüüp 1
            "value": true, // true = nõus, false = ei ole nõus
            "updated_at": "2016-12-09T14:23:53+02:00", // millal seda nõusolekut või keeldumist viimati muudeti
            "consent_by": { // kes andis nõusoleku (v keeldumise)
                "name_first":"Admin",
                "name_last":"Kasutaja"
            }
        },
        {
            "type": "alamtyyp-kaks", // nõusoleku (alam)tüüp 2
            "value": true,
            "updated_at":"2016-12-09T15:00:09+02:00",
            "consent_by":{
                "name_first":"Admin",
                "name_last":"Kasutaja"
            }
        }
    ]
},
{
    "id":"demo1-771",
    "name_first":"Teise Lapse",
    "name_last":"Perenimi",
    "idcode":"60412345679",
    "consents": [
        {
            "type":"alamtyyp-yks",
            "value":false,
            "updated_at":"2016-12-09T14:30:05+02:00",
            "consent_by":{
                "name_first":"Admin",
                "name_last":"Kasutaja"
            }
        }
    ]
}
]