Ako funguje API Optifory
Táto stránka opisuje tvar API: ako sa preukazuje totožnosť, ako postupujú verzie, v akých hraniciach sa požiadavka pohybuje, ako vyzerá chyba a ako sa vymieňajú údaje s vonkajším svetom.
Produkt sa vyvíja a plocha API sa ešte dopĺňa. Referenčný dokument ku koncovým bodom vyjde samostatne; táto stránka neuvádza žiadnu adresu ani ukážkové volanie, iba mechaniku.
Overenie totožnosti
Každá požiadavka patrí buď osobe, alebo registrovanej aplikácii. Požiadavka bez totožnosti, ktorá dorazí na chránený koncový bod, sa vráti ako neoverená.
- Token bearerPrístupový token cestuje v autorizačnej hlavičke požiadavky. Je podpísaný a hovorí len to, komu požiadavka patrí.
- Krátka životnosťPrístupový token vyprší po čase meranom v minútach; dĺžku určuje nastavenie nasadenia a predvolene je to tridsať minút.
- Obnovenie a rotáciaRelácia sa predlžuje obnovovacím tokenom a každé predĺženie vydá novú dvojicu. Ak sa už použitý obnovovací token predloží druhýkrát, zrušia sa všetky relácie danej osoby.
- Oprávnenia nie sú zapečené v tokeneToken nesie iba totožnosť; na to, čo osoba smie vidieť, sa systém pýta databázy pri každej požiadavke. Odobraté oprávnenie preto prestane platiť skôr, než vyprší token, ktorý má používateľ v ruke.
- Kľúč integrátoraRegistrovaná aplikácia sa pripája vlastným kľúčom. Čitateľná hodnota sa zobrazí jediný raz, pri vytvorení; uchováva sa jej odtlačok a netajná predpona, podľa ktorej sa kľúč rozpozná.
- Prístup udeľuje organizáciaNech je aplikácia akokoľvek rozšírená, bez oprávnenia zaznamenaného organizáciou neuvidí ani jediný riadok. Oprávnenie má dátum, vymedzený rozsah a dá sa odvolať.
Verziovanie
- Verzia je v cesteKoncové body sa zverejňujú za predponou verzie; dnešná plocha je verzia jeden.
- Rušivá zmena otvára novú cestuZmluva existujúceho koncového bodu sa na mieste neporušuje. Nekompatibilná zmena sa zverejní na novej ceste verzie, kým stará ďalej funguje.
- Dokument uvádza vlastnú verziuReferencia nesie číslo verzie, z ktorej bola vygenerovaná; na otázku, ktorú verziu čítate, odpovedá sám dokument.
Prostredia a limity
Referencia uvádza dve prostredia: produkčné a lokálne vývojové. Koreňová adresa sa integrátorovi odovzdáva spolu s jeho kľúčom; na tejto stránke sa nezverejňuje.
- Beh a pripravenosť sa merajú samostatneJeden koncový bod hovorí, že proces beží; druhý pošle skutočný dopyt do databázy a potvrdí, že je dostupná. O tom, či sa má posielať prevádzka, rozhoduje len ten druhý.
- Prehliadačové pôvody sú obmedzené zoznamomPožiadavky z iného pôvodu sa prijímajú len z vopred ohlásených pôvodov; kým je zoznam prázdny, prehliadačová požiadavka z iného pôvodu sa odmietne.
- Limit tela požiadavkyTelo požiadavky nesmie presiahnuť päť megabajtov. Veľké súbory údajov cestujú ako hromadná prenosová úloha s vlastným záznamom o stave, nie ako jediná požiadavka.
- Tajomstvá sa do denníka nezapisujúServerový denník neuchováva autorizačnú hlavičku, súbor cookie, heslo ani rodné číslo.
Limit rýchlosti
Limit platí na adresu a na minútu. Predvolene je to 120 požiadaviek za minútu a nastavuje sa pri nasadení. Zostatok sa hlási v hlavičkách každej odpovede.
| Hlavička odpovede | Čo hovorí |
|---|---|
| x-ratelimit-limit | Celkový prídel v rámci okna. |
| x-ratelimit-remaining | Koľko zostáva v tomto okne. |
| x-ratelimit-reset | Sekundy do obnovenia prídelu. |
| retry-after | Koľko sekúnd počkať pred opakovaním. Prítomné iba v odpovedi, ktorá požiadavku odmietla. |
Po prekročení limitu sa požiadavka odmietne a odpoveď v sekundách povie, ako dlho treba čakať. Opakovanie sa robí až po tomto čase, nie okamžite.
Formát chyby
Každá chyba sa vracia v rovnakej obálke: krátke kódové pole, podľa ktorého sa vetví stroj, a vysvetľujúce pole, ktoré si prečíta človek.
- errorKrátky kód, podľa ktorého sa rozhoduje klient.
- messageVysvetlenie toho, čo sa stalo.
| Stav | Pole s kódom | Čo to znamená |
|---|---|---|
| 400 | Bad Request | Požiadavka nezodpovedá schéme. Vysvetlenie pomenuje pole, ktoré chýba alebo je neplatné. |
| 401 | unauthenticated | Chýba platná totožnosť: token nebol odoslaný, vypršal alebo sa neoveril. |
| 404 | Not Found | Taký koncový bod neexistuje alebo taký záznam neexistuje. |
| 429 | Too Many Requests | Limit rýchlosti bol prekročený; odpoveď hovorí, ako dlho treba čakať. |
| 5xx | internal_error | Neočakávané zlyhanie. Podrobnosť sa klientovi neodovzdáva; zapisuje sa do serverového denníka. |
Stránkovanie
Koncové body, ktoré vracajú zoznamy, prijímajú tie isté dva parametre a vracajú tie isté počítadlá, takže stránkujúci klient sa nepíše nanovo pre každý koncový bod.
- limitKoľko záznamov má obsahovať jedna strana. Najmenej jeden, najviac dvesto; ak nie je nastavené, päťdesiat.
- offsetKoľko záznamov sa má preskočiť. Začína sa od nuly.
- totalKoľko záznamov celkovo zodpovedá filtrom.
- countKoľko záznamov táto odpoveď skutočne nesie.
Odpoveď zopakuje aj limit a posun, ktoré použila; klient si svoju pozíciu prečíta z odpovede namiesto toho, aby ju odhadoval.
Výmena údajov a webhooky
Režim výmeny je nastavenie, nie samostatný produkt: každá registrovaná aplikácia nesie režim, v ktorom pracuje, na vlastnom zázname.
| Režim | Čo to znamená |
|---|---|
| Jednosmerne — von | Optifora zverejňuje údaje; druhá strana ich číta alebo sa prihlási na odber udalostí. |
| Jednosmerne — dnu | Druhá strana údaje posiela; Optifora ich overí a zapíše. |
| Obojsmerne | Zapisujú obe strany; pravidlo riešenia konfliktu je určené vopred. |
| Podanie rúk | Každý prenos otvára reláciu: ponuka, overenie, schválenie, prenos a potvrdenka. Potvrdenka zostáva obom stranám. |
- Udalosti sa posielajú vonWebhook posiela udalosť na adresu spätného volania, ktorú ohlásila registrovaná aplikácia. Udalosť, ktorú sa nepodarí doručiť, zostáva vo fronte a opakuje sa; nikdy sa ticho nezahodí.
- Tá istá požiadavka nezapíše dvakrátZapisovacia požiadavka nesie kľúč idempotencie. Druhá požiadavka s rovnakým kľúčom nevytvorí druhý záznam.
- Každé volanie sa meriaKto volal, kedy, s akým rozsahom a s akým výsledkom — všetko sa zaznamenáva. Ten istý záznam odpovedá na ladenie aj na otázku, kto tieto údaje stiahol.
- Naše vlastné aplikácie používajú tie isté dvereNijaká privilegovaná druhá cesta neexistuje. Naša vlastná integrácia je dôkazom plochy, s ktorou sa stretne vonkajší vývojár.
Dátový model výmennej vrstvy je hotový; jej koncové body ešte nie sú zverejnené. Keď budú, táto časť odkáže na ich záznamy v referencii.
Referenčné dokumenty
Referencia sa nepíše ručne; generuje sa zo schém koncových bodov. Ako každý koncový bod odovzdá svoju schému, dokument sa dopĺňa sám, takže dokument a správanie sa nemôžu rozísť.
- Dnes: v prípraveSchémy sa presúvajú modul po module. Skôr než dokument vyjde, bude v ňom vidieť požiadavku a odpoveď každého koncového bodu.
- Zverejnia sa dva formátyStrojovo čitateľný dokument OpenAPI a referenčná stránka vytvorená z toho istého dokumentu, ktorú možno prezerať v prehliadači.
- Prístup má úrovnePrehľad je otvorený pre každého. Celá referencia môže byť za dokumentačným tokenom, ktorý dostane registrovaný integrátor; produkčné kľúče a adresy spätných volaní nie sú vecou dokumentácie vôbec — patria k záznamu aplikácie.
- Štandard adriesZverejnia sa dve referencie a ich adresy sú pevné: client-api.optifora.com/docs je otvorená, admin-api.optifora.com/docs vyžaduje oprávnenie a je zvonka uzavretá. Dnes nie je v prevádzke ani jedna; odkazy sa do tejto časti doplnia, keď budú.
Ak je váš plán integrácie už jasný, napíšte nám cez kontaktnú stránku: budete medzi prvými, ktorým oznámime otvorenie plochy.
Máte konkrétnu požiadavku?
Tieto stránky vysvetľujú, ako proces podpory funguje. Ak máte požiadavku alebo otázku, napíšte nám z kontaktnej stránky.
Prejsť na kontaktnú stránku