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 (API endpointi, OAuth, serveru adreses, testēšanas un produkcijas vides) ir publiskajā API dokumentācijā. Šajā rakstā skaidrots, kas jāiesniedz pieteikumā, kā atšķiras pamata un paplašināta integrācija, kā norit izvērtēšana un kas jāievēro pēc pieteikuma iesniegšanas.
Pamata un paplašināta integrācija
Pamata integrācija — scenāriji, kas atbilst publiski dokumentētajam API. Parasti lietotājs pārlūkā autorizējas Mykoob un apstiprina piekļuvi. Ārējai lietotnei tiek izdots piekļuves žetons (access token), un tai ir pieejams dokumentācijā norādītais datu apjoms. Plašāk — dokumentācijā.
Paplašināta integrācija — scenāriji, kas pārsniedz publiski dokumentēto API: plašāks vai cits datu apjoms, atšķirīgi drošības pieņēmumi vai īpašs process, piemēram, darbības ar žurnālu, vērtējumiem vai sasaisti ar citiem pakalpojumiem. Šādiem scenārijiem nav viena standarta pieslēgšanās modeļa, tāpēc 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".
Kāpēc vajag konkrētu mērķi un procesu
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 veiks darbības un kāds datu apjoms patiesi nepieciešams.
Viena teikuma pieprasījums nav pietiekams — nepieciešams īss, pārdomāts procesa apraksts.
Kas jāiekļauj pieteikumā
Vienā e-pastā vai pielikumā:
Iestādes vai uzņēmuma nosaukums (oficiālais).
Kontaktpersona: vārds, uzvārds, e-pasts, tālrunis.
Mērķis — kādu problēmu risina un kam paredzēts (skola, vecāki, skolēni, cits pakalpojums u. c.).
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.
Ja tiek lietots OAuth ar atgriešanos integrētajā lietotnē — norādīt redirect URI (HTTPS atgriešanās adresi). OAuth plūsmā caur šo adresi 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.Ja jau zināms, ka vajadzīgs vairāk nekā pamata, publiski aprakstītais datu apjoms — norādīt, kas tieši nepieciešams un kāpēc.
Pieteikums: [email protected].
Kā norit process
Pieteikums — informācija no iepriekšējā saraksta.
Izvērtēšana — tiek pārbaudīts, vai scenārijs ietilpst pamata dokumentētajā API, vai nepieciešama tālāka saskaņošana. Mykoob var lūgt precizējumus.
OAuth klients (ja attiecas) — pēc skaidra pieteikuma tiek izsniegti client id, client secret un scopes. Žetonu iegūšana, API izsaukumi un vides ir aprakstītas publiskajā dokumentācijā.
Izstrāde — testēšanai izmantot testēšanas vidi. Pirms īstas lietošanas integrācija jāpārbauda produkcijas vidē. Vides un adreses norādītas dokumentācijā.
Paplašināti scenāriji — pēc sākotnējā vērtējuma atsevišķi saskaņojami nākamie soļi: datu un funkciju apjoms, nosacījumi un, ja nepieciešams, papildu materiāli.
client secret un piekļuves žetoni (access tokens) ir slepeni. Tie jāglabā tikai drošā vidē, piemēram, servera konfigurācijā vai slepeno atslēgu krātuvē, nevis publiskā kodā.
Kas jāievēro pēc pieteikuma
Izstrādātājam: jāiesniedz precīzs mērķa un procesa apraksts, jāievēro drošas izstrādes prakses un publiskā dokumentācija. Testēšanas un produkcijas vides nedrīkst sajaukt. Konkrēti URL un iestatījumi ir norādīti dokumentācijā.
Mykoob: atbild uz pieteikumu un norāda nākamos soļus. Ja pieteikums ir pietiekami skaidrs, tiek izsniegti OAuth klienta reģistrācijas dati. Paplašināta dokumentācija vai iekšēji materiāli tiek izsniegti tikai pēc konkrētas vienošanās.
Jautājumi un precizējumi: [email protected].
Piemēram, ārēju mācību uzdevumu integrācijās Mykoob var nosūtīt pieprasījumus uz partnera sistēmas API endpoint. Šādam scenārijam nepieciešama atsevišķa vienošanās, un tas attiecas uz paplašināto līmeni, nevis pamata API.
Ja pēc šī raksta un dokumentācijas nav skaidrs, kurā līmenī ietilpst plānotā integrācija, sazināties ar [email protected] pirms apjomīgas izstrādes.