Így működik az Optifora API
Ez az oldal az API alakját írja le: hogyan igazolható az azonosság, hogyan lépnek előre a verziók, milyen korlátok között marad egy kérés, hogyan néz ki egy hiba, és hogyan zajlik az adatcsere a külvilággal.
A termék fejlesztés alatt áll, az API felülete még készül. A végpontok referenciadokumentuma külön jelenik meg; ez az oldal nem tartalmaz sem címet, sem mintahívást, csak a működés elvét.
Hitelesítés
Minden kérés vagy egy személyhez, vagy egy regisztrált alkalmazáshoz tartozik. A védett végpontra azonosság nélkül érkező kérés hitelesítetlenként tér vissza.
- Bearer tokenA hozzáférési token a kérés engedélyezési fejlécében utazik. Aláírt, és csak annyit mond meg, hogy a kérés kihez tartozik.
- Rövid élettartamA hozzáférési token percekben mért idő után lejár; a hossz üzemeltetési beállítás, alapértelmezetten harminc perc.
- Megújítás és rotációA munkamenetet frissítő token hosszabbítja meg, és minden hosszabbítás új párt bocsát ki. Ha egy már felhasznált frissítő tokent másodszor is bemutatnak, az adott személy minden munkamenetét visszavonjuk.
- A jogosultságok nincsenek beleégetve a tokenbeA token csak azonosságot hordoz; hogy ki mit láthat, azt minden kérésnél az adatbázistól kérdezzük meg. A visszavont jogosultság ezért már azelőtt megszűnik működni, hogy a kézben lévő token lejárna.
- Integrátori kulcsA regisztrált alkalmazás a saját kulcsával kapcsolódik. A nyílt értéket egyszer, a létrehozáskor mutatjuk meg; tárolni a lenyomatát és azt a nem titkos előtagot tároljuk, amelyről a kulcs felismerhető.
- A hozzáférést a szervezet adja megBármilyen széles körben használják is az alkalmazást, a szervezet által rögzített hozzájárulás nélkül egyetlen sort sem lát. A hozzájárulás dátumhoz kötött, hatókörrel bír és visszavonható.
Verziózás
- A verzió az útvonalban vanA végpontok verzióelőtag mögött jelennek meg; a mai felület az első verzió.
- A törő változás új útvonalat nyitMeglévő végpont szerződését nem törjük meg helyben. Az összeférhetetlen változás új verzióútvonalon jelenik meg, miközben a régi tovább működik.
- A dokumentum megmondja a saját verziójátA referencia magán viseli azt a verziószámot, amelyből készült; hogy melyik verziót olvassa, arra maga a dokumentum válaszol.
Környezetek és korlátok
A referencia két környezetet nevez meg: éles és helyi fejlesztői. A gyökércímet az integrátor a kulcsával együtt kapja meg; ezen az oldalon nem tesszük közzé.
- Az életjel és a készenlét külön mérésAz egyik végpont azt mondja meg, hogy a folyamat fut; a másik valódi lekérdezést küld az adatbázisnak, és megerősíti, hogy elérhető. Csak a második dönti el, hogy szabad-e forgalmat küldeni.
- A böngészőeredetek listához kötöttekA más eredetű kéréseket csak előre bejelentett eredetekről fogadjuk el; amíg a lista üres, a böngészőből érkező, más eredetű kérést elutasítjuk.
- TörzsméretkorlátA kérés törzse nem haladhatja meg az öt megabájtot. A nagy adathalmazok nem egyetlen kérésként, hanem saját állapotrekorddal rendelkező tömeges átviteli feladatként utaznak.
- Titkok nem kerülnek a naplóbaA kiszolgáló naplója nem őriz meg engedélyezési fejlécet, sütit, jelszót és személyazonosító számot.
Sebességkorlát
A korlát címenként és percenként értendő. Alapértéke percenként 120 kérés, és üzembe helyezéskor állítható be. A maradék keretet minden válasz fejlécei jelzik.
| Válaszfejléc | Mit mond meg |
|---|---|
| x-ratelimit-limit | A teljes keret az ablakon belül. |
| x-ratelimit-remaining | Mennyi maradt ebben az ablakban. |
| x-ratelimit-reset | Hány másodperc múlva újul meg a keret. |
| retry-after | Hány másodperc múlva próbálkozzon újra. Csak azon a válaszon szerepel, amely elutasította a kérést. |
A korlát átlépése után a kérést elutasítjuk, és a válasz másodpercben megmondja, mennyit kell várni. Az újrapróbálkozás ez után az idő után történik, nem azonnal.
Hibaformátum
Minden hiba ugyanabban a burokban tér vissza: egy rövid kódmező, amely alapján a gép elágazik, és egy magyarázó mező, amelyet ember olvas.
- errorA rövid kód, amely alapján a kliens dönt.
- messageA történtek magyarázata.
| Állapot | Kódmező | Mit jelent |
|---|---|---|
| 400 | Bad Request | A kérés nem felel meg a sémának. A magyarázat megnevezi a hiányzó vagy érvénytelen mezőt. |
| 401 | unauthenticated | Nincs érvényes azonosság: nem érkezett token, lejárt, vagy nem ellenőrizhető. |
| 404 | Not Found | Nincs ilyen végpont, vagy nincs ilyen rekord. |
| 429 | Too Many Requests | A sebességkorlát túllépve; a válasz megmondja, mennyit kell várni. |
| 5xx | internal_error | Váratlan hiba. A részletet nem adjuk át a kliensnek; a kiszolgáló naplójába kerül. |
Lapozás
A listát visszaadó végpontok ugyanazt a két paramétert veszik át és ugyanazokat a számlálókat adják vissza, így a lapozó klienst nem kell végpontonként újraírni.
- limitHány rekordot tartalmazzon egy oldal. Legalább egyet, legfeljebb kétszázat; beállítás híján ötvenet.
- offsetHány rekordot hagyjon ki. Nullától indul.
- totalÖsszesen hány rekord felel meg a szűrőknek.
- countHány rekordot hordoz ténylegesen ez a válasz.
A válasz visszaadja az alkalmazott limit és offset értéket is; a kliens így a válaszból olvassa ki a helyzetét, nem találgatja.
Adatcsere és webhookok
Az adatcsere módja beállítás, nem külön termék: minden regisztrált alkalmazás a saját rekordján hordozza, milyen módban működik.
| Mód | Mit jelent |
|---|---|
| Egyirányú — kimenő | Az Optifora adatot tesz közzé; a másik oldal olvassa, vagy feliratkozik az eseményekre. |
| Egyirányú — bejövő | A másik oldal küldi az adatot; az Optifora ellenőrzi és rögzíti. |
| Kétirányú | Mindkét oldal ír; az ütközés feloldásának szabálya előre rögzített. |
| Kézfogás | Minden átadás munkamenetet nyit: ajánlat, ellenőrzés, jóváhagyás, átadás és átvételi elismervény. Az elismervény mindkét oldalnál megmarad. |
- Az eseményeket kifelé küldjükA webhook az eseményt arra a visszahívási címre küldi, amelyet a regisztrált alkalmazás bejelentett. A kézbesíthetetlen esemény sorban marad, és újrapróbálkozunk vele; soha nem vész el csendben.
- Ugyanaz a kérés nem ír kétszerAz író kérés idempotenciakulcsot hordoz. Az azonos kulcsú második kérés nem hoz létre második rekordot.
- Minden hívást mérünkKi hívott, mikor, milyen hatókörrel és milyen eredménnyel — mindezt rögzítjük. Ugyanez a nyilvántartás válaszol a hibakeresésre és arra a kérdésre is, hogy ki kérte le ezt az adatot.
- A saját alkalmazásaink ugyanazon az ajtón lépnek beNincs kiváltságos második útvonal. A saját integrációnk bizonyítja azt a felületet, amellyel a külső fejlesztő találkozik.
Az adatcsere-réteg adatmodellje készen áll, a végpontjai még nem jelentek meg. Amint megjelennek, ez a szakasz a referenciában lévő tételeikre fog hivatkozni.
Referenciadokumentumok
A referencia nem kézzel készül, hanem a végpontsémákból generáljuk. Ahogy az egyes végpontok átadják a sémájukat, a dokumentum magától telik meg, így a dokumentum és a viselkedés nem szakadhat el egymástól.
- Ma: előkészítés alattA sémák modulonként haladnak. A dokumentum megjelenése előtt minden végpont kérése és válasza látható lesz benne.
- Két formátumban jelenik megEgy géppel olvasható OpenAPI-dokumentum, és egy ugyanabból a dokumentumból származó, böngészőben átnézhető referenciaoldal.
- A hozzáférés szintezettAz áttekintés bárki előtt nyitva áll. A teljes referencia egy regisztrált integrátornak adott dokumentációs token mögött állhat; az éles kulcsok és a visszahívási címek pedig egyáltalán nem dokumentációs kérdések — az alkalmazás saját rekordjához tartoznak.
- CímszabványKét referencia jelenik meg, rögzített címen: a client-api.optifora.com/docs nyílt, az admin-api.optifora.com/docs engedélyhez kötött és kívülről zárt. Egyik sem él még ma; a hivatkozásokat ebbe a szakaszba tesszük be, amint elindulnak.
Ha az integrációs terve már kész, írjon nekünk a kapcsolatfelvételi oldalról: Ön lesz az elsők között, akiket értesítünk a felület megnyitásáról.
Konkrét kérése van?
Ezek az oldalak leírják, hogyan működik a támogatási folyamat. Ha kérése vagy kérdése van, írjon nekünk a kapcsolatfelvételi oldalról.
Tovább a kapcsolat oldalra