Referenca API
Javne končne točke API za razvijalce: obrazci, gradnik, konfigurator izdelkov in več.
Ta referenca opisuje izključno resnične, javno uporabne končne točke JSON -- način, pot, vrsto avtentikacije, obvezne parametre, primer zahteve in odgovora ter dokumentirane kode napak za vsako končno točko. Splošen sistem API-ključev za razvijalce pri Zentor ne obstaja; dostop poteka glede na pot bodisi brez avtentikacije bodisi prek žetona za vdelavo gradnika s preverjanjem izvora (origin). Interne poti nadzorne plošče in končne točke glavnega skrbnika (Master-Admin) namenoma niso del te javne reference, ker so dosegljive izključno prek običajne prijavne seje.
Vsak vnos končne točke ima opombo o testu v živo, ki razkrije, ali podatek izhaja iz sheme registra, avtomatiziranega testa ali dejanskega opazovanja v živo -- zgolj podobnost z delujočo potjo v kodi pri tem ne velja za popoln dokaz. Tehnično uspešen klic poleg tega vedno potrjuje samo obdelavo same zahteve, ne pa samodejno poznejših postopkov, kot so dostava e-pošte, zaključek plačila ali zaključena prijava SSO.
Zaščita je odvisna od posamezne skupine. Javne pravne, trženjske in obrazčne končne točke ne potrebujejo seje nadzorne plošče. Gradnik klepeta pa uporablja glavo `X-Widget-Token` in seznam dovoljenih izvorov (origin allowlist). Prijave v nadzorno ploščo vrnejo sejni JWT z veljavnostjo dvanajst ur in žeton za osvežitev z veljavnostjo sedem dni. Končne točke SSO delujejo z lastnimi enkratnimi kodami in poteki povratnih klicev (callback).
Vsako stran končne točke berite kot samostojno pogodbo. Odločilni so način HTTP, pot, obvezni parametri, podatkovni tipi, telo zahteve, struktura odgovora, kode napak in idempotentnost. Primer prikazuje možno obliko, vendar ne nadomešča preverjanja dejanskega odgovora. Stanje konfiguracije, preverjanja veljavnosti, dovoljenja in zunanji ponudniki lahko spremenijo izid.
Potrjena omejitev zahtev za celotno platformo znaša 2.000 zahtev v 15 minutah. Ločene omejitve za posamezne končne točke niso povsod dokumentirane. Odjemalci zato ne bi smeli uporabljati po nepotrebnem tesnih zank poizvedovanja (polling). Pri neidempotentnih operacijah lahko samodejne ponovitve ustvarijo podvojene zapise ali sporočila.
Občutljive vrednosti ne sodijo v dnevnike. Mednje spadajo gesla, žetoni za ponastavitev, kode za preverjanje, žetoni gradnika, ID-ji sej in resnični osebni vzorčni podatki. V dokumentaciji in testih uporabljajte anonimizirane vrednosti. Opombe o testih v živo morajo pravilno odražati dejanski dokaz.