Kako deluje API Optifora
Ta stran opisuje obliko vmesnika API: kako se dokaže istovetnost, kako napredujejo različice, znotraj katerih omejitev ostaja zahteva, kako izgleda napaka in kako se podatki izmenjujejo z zunanjim svetom.
Izdelek je v razvoju in površina API se še dopolnjuje. Referenčni dokument za končne točke bo objavljen posebej; ta stran ne nosi ne naslova ne vzorčnega klica, temveč samo mehaniko.
Preverjanje istovetnosti
Vsaka zahteva pripada bodisi osebi bodisi registrirani aplikaciji. Zahteva brez istovetnosti, ki doseže zaščiteno končno točko, se vrne kot nepreverjena.
- Žeton BearerDostopni žeton potuje v avtorizacijski glavi zahteve. Podpisan je in pove samo to, komu zahteva pripada.
- Kratka življenjska dobaDostopni žeton poteče po obdobju, merjenem v minutah; dolžina je nastavitev namestitve in privzeto znaša trideset minut.
- Osvežitev in rotacijaSeja se podaljša z osvežitvenim žetonom, vsako podaljšanje pa izda nov par. Če je porabljen osvežitveni žeton predložen drugič, se prekličejo vse seje te osebe.
- Dovoljenja niso vgrajena v žetonŽeton nosi samo istovetnost; kaj sme oseba videti, se pri vsaki zahtevi vpraša podatkovno zbirko. Odvzeto dovoljenje zato neha delovati še preden poteče žeton, ki ga ima oseba v rokah.
- Ključ integratorjaRegistrirana aplikacija se poveže z lastnim ključem. Čista vrednost se pokaže enkrat, ob nastanku; shrani se njen izvleček in nezaupna predpona, po kateri je ključ prepoznaven.
- Dostop odobri organizacijaNaj bo aplikacija še tako razširjena, brez privolitve, ki jo zabeleži organizacija, ne vidi niti ene vrstice. Privolitev je datirana, omejena po obsegu in preklicljiva.
Vodenje različic
- Različica živi v potiKončne točke so objavljene za predpono različice; današnja površina je različica ena.
- Prelomna sprememba odpre novo potPogodba obstoječe končne točke se ne prelomi na mestu. Nezdružljiva sprememba se objavi na novi poti različice, stara pa deluje naprej.
- Dokument sam navede svojo različicoReferenca nosi številko različice, iz katere je bila ustvarjena; katero različico berete, odgovori dokument sam.
Okolja in omejitve
Referenca navaja dve okolji: produkcijo in krajevni razvoj. Korenski naslov se integratorju izroči skupaj z njegovim ključem; na tej strani ni objavljen.
- Živost in pripravljenost se merita ločenoEna končna točka pove, da proces teče; druga pošlje resnično poizvedbo v podatkovno zbirko in potrdi, da je dosegljiva. Samo druga odloči, ali naj se promet pošlje.
- Brskalniški izvori so omejeni na seznamZahteve iz drugih izvorov so sprejete samo z vnaprej prijavljenih izvorov; dokler je seznam prazen, je brskalniška zahteva iz drugega izvora zavrnjena.
- Omejitev telesaTelo zahteve ne sme presegati petih megabajtov. Veliki nizi potujejo kot množičen prenosni posel z lastnim zapisom stanja, ne kot ena sama zahteva.
- Skrivnosti se ne zapisujejo v dnevnikStrežniški dnevnik ne hrani niti avtorizacijske glave niti piškotka niti gesla niti nacionalne identifikacijske številke.
Hitrostna omejitev
Omejitev velja na naslov in na minuto. Privzeto je 120 zahtev na minuto in se določi ob namestitvi. Kaj je ostalo, sporočajo glave v vsakem odgovoru.
| Glava odgovora | Kaj pove |
|---|---|
| x-ratelimit-limit | Skupna dovoljena količina znotraj okna. |
| x-ratelimit-remaining | Koliko je ostalo v tem oknu. |
| x-ratelimit-reset | Sekunde do obnovitve dovoljene količine. |
| retry-after | Koliko sekund do ponovnega poskusa. Prisotno samo v odgovoru, ki je zahtevo zavrnil. |
Ko je omejitev presežena, je zahteva zavrnjena, odgovor pa v sekundah pove, koliko časa je treba počakati. Ponovni poskus se opravi po tem času, ne takoj.
Oblika napake
Vsaka napaka se vrne v isti ovojnici: kratko kodno polje, po katerem se odloči stroj, in pojasnilno polje, ki ga prebere človek.
- errorKratka koda, po kateri se odloči odjemalec.
- messagePojasnilo, kaj se je zgodilo.
| Stanje | Polje kode | Kaj pomeni |
|---|---|---|
| 400 | Bad Request | Zahteva ne ustreza shemi. Pojasnilo poimenuje polje, ki manjka ali ni veljavno. |
| 401 | unauthenticated | Veljavne istovetnosti ni: žeton ni bil poslan, je potekel ali ni bil overjen. |
| 404 | Not Found | Take končne točke ni ali pa takega zapisa ni. |
| 429 | Too Many Requests | Hitrostna omejitev je bila presežena; odgovor pove, koliko časa je treba počakati. |
| 5xx | internal_error | Nepričakovana napaka. Podrobnost se ne izroči odjemalcu; zapiše se v strežniški dnevnik. |
Ostranjevanje
Končne točke, ki vračajo sezname, sprejmejo ista dva parametra in vrnejo iste števce, zato odjemalca za ostranjevanje ni treba pisati znova za vsako končno točko.
- limitKoliko zapisov naj vsebuje stran. Najmanj enega, največ dvesto; petdeset, kadar ni določeno.
- offsetKoliko zapisov naj se preskoči. Začne se pri nič.
- totalKoliko zapisov skupno ustreza filtrom.
- countKoliko zapisov ta odgovor dejansko nosi.
Odgovor tudi odzrcali limit in offset, ki ju je uporabil; odjemalec svoj položaj prebere iz odgovora, namesto da bi ga ugibal.
Izmenjava podatkov in spletne kljuke
Način izmenjave je nastavitev, ne ločen izdelek: vsaka registrirana aplikacija nosi način, v katerem dela, v svojem zapisu.
| Način | Kaj pomeni |
|---|---|
| Enosmerno — navzven | Optifora objavlja podatke; druga stran jih bere ali se naroči na dogodke. |
| Enosmerno — navznoter | Druga stran potisne podatke; Optifora jih preveri in zapiše. |
| Dvosmerno | Pišeta obe strani; pravilo za spor je določeno vnaprej. |
| Rokovanje | Vsak prenos odpre sejo: ponudba, preverjanje, odobritev, prenos in potrdilo. Potrdilo ostane pri obeh straneh. |
- Dogodki se potiskajo navzvenSpletna kljuka pošlje dogodek na povratni naslov, ki ga je prijavila registrirana aplikacija. Dogodek, ki ga ni mogoče dostaviti, ostane v čakalni vrsti in se ponovi; nikoli ni tiho zavržen.
- Ista zahteva ne zapiše dvakratZahteva za pisanje nosi ključ idempotentnosti. Druga zahteva z istim ključem ne ustvari drugega zapisa.
- Vsak klic se izmeriKdo je klical, kdaj, s katerim obsegom in s kakšnim izidom — vse se zabeleži. Isti zapis odgovori tako na razhroščevanje kot na vprašanje, kdo je te podatke potegnil.
- Naše aplikacije uporabljajo ista vrataPrivilegirane druge poti ni. Naša lastna integracija je dokaz za površino, na katero naleti zunanji razvijalec.
Podatkovni model za izmenjevalno plast je vzpostavljen; njegove končne točke še niso objavljene. Ko bodo, bo ta razdelek povezal do njihovih vnosov v referenci.
Referenčni dokumenti
Reference ne pišemo ročno; ustvarjena je iz shem končnih točk. Ko vsaka končna točka izroči svojo shemo, se dokument izpolni sam, zato dokument in vedenje ne moreta razhajati.
- Danes: v pripraviSheme se selijo modul za modulom. Preden bo dokument objavljen, bosta v njem vidni zahteva in odgovor vsake končne točke.
- Objavljeni bosta dve oblikiStrojno berljiv dokument OpenAPI in referenčna stran, izrisana iz istega dokumenta ter berljiva v brskalniku.
- Dostop je stopenjskiPregled je odprt vsakomur. Celotna referenca lahko stoji za dokumentacijskim žetonom, izdanim registriranemu integratorju; produkcijski ključi in povratni naslovi sploh niso stvar dokumentacije — sodijo v zapis aplikacije.
- Standard naslovaObjavljeni sta dve referenci in njuna naslova sta stalna: client-api.optifora.com/docs je odprt, admin-api.optifora.com/docs zahteva pooblastilo in je zaprt za zunanji svet. Danes ni v živo še nobeden; povezavi bosta dodani v ta razdelek, ko bosta.
Če je vaš načrt integracije že jasen, nam pišite s strani za stik: med prvimi boste izvedeli, kdaj se površina odpre.
Imate določeno zahtevo?
Te strani pojasnjujejo, kako poteka postopek podpore. Če imate zahtevo ali vprašanje, nam pišite s strani za stik.
Pojdite na stran za stik