Raksts paredzēts iestādēm un ārējo pakalpojumu izstrādātājiem — lai pirms izstrādes noskaidrotu integrācijas līmeni un sagatavotu pieteikumu.

Tehniskā specifikācija (endpointi, OAuth, serveru adreses, testēšanas un produkcijas vide) ir publiskajā API dokumentācijā. Šajā rakstā: kas jāiesniedz pieteikumā; atšķirība starp pamata un paplašinātu integrāciju; kā norit izvērtēšana un ko sagaidīt no abām pusēm.

Pamata integrācija — scenāriji, kas atbilst publiski dokumentētajam API: tipiski lietotājs pārlūkā autorizējas Mykoob un apstiprina piekļuvi; ārējai lietotnei tiek izdots piekļuves žetons (access token) un pieejams dokumentācijā norādītais datu apjoms. Sīkāk — dokumentācijā.

Paplašināta integrācija — viss, kas pārsniedz publiski dokumentēto API: plašāks vai cits datu apjoms, citādi drošības vai procesa pieņēmumi (piemēram, žurnāls, vērtējumi, saites ar citiem pakalpojumiem). Šādiem scenārijiem nav viena standarta pieslēgšanās modeļa — nepieciešama atsevišķa saskaņošana ar Mykoob. Ilgtermiņa partnerību vai dziļāku integrāciju iespējams izvērtēt tikai tad, ja pieteikumā ir skaidrs mērķis un process, nevis vispārīga vēlme "pieslēgties API".

Integrācija skar personu un mācību datus. Lai noteiktu atbilstību un nākamos soļus, jāsaprot: ko integrācija nodrošinās, kādā secībā lietotājs veic darbības un kāds datu apjoms patiesi nepieciešams. Viena teikuma pieprasījums nepietiek — nepieciešams īss, pārdomāts procesa apraksts.

Vienā e-pastā vai pielikumā:

1. Iestādes vai uzņēmuma nosaukums (oficiālais).

2. Kontaktpersona: vārds, uzvārds, e-pasts, tālrunis.

3. Mērķis — kādu problēmu risina un kam paredzēts (skola, vecāki, skolēni, cits pakalpojums u. c.).

4. Plānotais process — īsi soļi: kur sākas darbība, kur nepieciešami Mykoob dati, kur tie tiek rādīti vai apstrādāti.

5. Ja lietots OAuth ar atgriešanos integrētajā lietotnē — norādīt redirect URI (HTTPS atgriešanās adrese): caur to OAuth plūsmā tiek saņemts authorization code un pēc tam piekļuves žetons (access token). Tā pati adrese jānorāda, reģistrējot OAuth klientu. Piemērs: https://app.example.com/oauth/mykoob/callback.

6. Ja jau zināms, ka vajadzīgs vairāk nekā pamata, publiski aprakstītais apjoms — norādīt, kas tieši un kāpēc.

Pieteikums: [email protected].

1. Pieteikums — informācija no iepriekšējā saraksta.

2. Izvērtēšana — vai scenārijs ietilpst pamata dokumentētajā API, vai vajadzīga tālāka saskaņošana; Mykoob var lūgt precizējumu.

3. OAuth klients (ja attiecas) — pēc skaidra pieteikuma tiek izsniegti client id, client secret un scopes; žetonu iegūšana, API izsaukumi un vide — pēc publiskās dokumentācijas.

4. Izstrāde — testēšanai izmantot testēšanas vidi, pirms īstas lietošanas — pārbaudīt produkcijas vidē; vides un adreses — dokumentācijā.

5. Paplašināti scenāriji — pēc sākotnējā vērtējuma atsevišķi saskaņojami soļi (datu un funkciju apjoms, nosacījumi, iespējams papildu materiāls).

No izstrādātāja puses: precīzs mērķa un procesa apraksts; drošas prakses un publiskās dokumentācijas ievērošana; testēšanas un produkcijas vides nesajaukt (konkrēti URL un iestatījumi — dokumentācijā).

No Mykoob puses: atbilde uz pieteikumu un norāde uz nākamajiem soļiem; OAuth klienta reģistrācijas dati, kad pieteikums ir pietiekami skaidrs; paplašinātas dokumentācijas vai iekšēju materiālu izsniegšana tikai pēc konkrētas vienošanās. Jautājumi un precizējumi — [email protected].

Ja pēc šī raksta un dokumentācijas nav skaidrs, kurā līmenī ir plānotā integrācija, sazināties ar [email protected] pirms apjomīgas izstrādes.