Jak funguje API Optifory
Tato stránka popisuje podobu API: jak se prokazuje identita, jak se posouvají verze, v jakých mezích se požadavek pohybuje, jak vypadá chyba a jak se data vyměňují s vnějším světem.
Produkt se vyvíjí a rozhraní API se stále dokončuje. Referenční dokument ke koncovým bodům bude zveřejněn samostatně; tato stránka neuvádí žádnou adresu ani ukázkové volání, jen princip fungování.
Ověření identity
Každý požadavek patří buď osobě, nebo registrované aplikaci. Požadavek bez identity, který dorazí na chráněný koncový bod, se vrací jako neověřený.
- Token typu BearerPřístupový token cestuje v autorizační hlavičce požadavku. Je podepsaný a říká pouze to, komu požadavek patří.
- Krátká životnostPřístupový token vyprší po době měřené v minutách; její délka je nastavením nasazení a ve výchozím stavu činí třicet minut.
- Obnovení a rotaceRelace se prodlužuje obnovovacím tokenem a každé prodloužení vydá novou dvojici. Pokud je již použitý obnovovací token předložen podruhé, jsou všechny relace dané osoby odvolány.
- Oprávnění nejsou zapečena v tokenuToken nese pouze identitu; na to, co smí osoba vidět, se u každého požadavku ptáme databáze. Odebrané oprávnění proto přestane fungovat dřív, než vyprší token, který má uživatel v ruce.
- Klíč integrátoraRegistrovaná aplikace se připojuje vlastním klíčem. Otevřená hodnota se zobrazí jen jednou, při vytvoření; uložen zůstává její otisk a netajná předpona, podle níž lze klíč rozpoznat.
- Přístup uděluje organizaceAť je aplikace rozšířená sebevíc, bez oprávnění zaznamenaného organizací neuvidí ani jeden řádek. Oprávnění má datum, rozsah a lze je odvolat.
Verzování
- Verze je v cestěKoncové body se zveřejňují za předponou s verzí; dnešní rozhraní je verze jedna.
- Nekompatibilní změna otevírá novou cestuKontrakt existujícího koncového bodu se na místě neporušuje. Nekompatibilní změna se zveřejňuje na nové cestě s verzí, zatímco stará dál funguje.
- Dokument uvádí vlastní verziReference nese číslo verze, ze které byla vygenerována; na otázku, kterou verzi čtete, odpovídá sám dokument.
Prostředí a limity
Referenční dokument uvádí dvě prostředí: produkční a lokální vývojové. Kořenová adresa se integrátorovi předává spolu s jeho klíčem; na této stránce zveřejněna není.
- Běh a připravenost se měří odděleněJeden koncový bod říká, že proces běží; druhý pošle skutečný dotaz do databáze a potvrdí, že je dostupná. O tom, zda se má posílat provoz, rozhoduje až ten druhý.
- Původy prohlížeče jsou omezeny na seznamPožadavky z jiného původu se přijímají jen z předem ohlášených původů; dokud je seznam prázdný, je požadavek z prohlížeče z jiného původu odmítnut.
- Limit tělaTělo požadavku nesmí přesáhnout pět megabajtů. Velké sady cestují jako hromadná přenosová úloha s vlastním záznamem stavu, ne jako jediný požadavek.
- Tajemství se do protokolu nezapisujíServerový protokol neuchovává autorizační hlavičku, soubor cookie, heslo ani rodné číslo.
Limit četnosti
Limit platí na adresu a na minutu. Výchozí hodnota je 120 požadavků za minutu a nastavuje se při nasazení. Zbývající příděl se hlásí v hlavičkách každé odpovědi.
| Hlavička odpovědi | Co udává |
|---|---|
| x-ratelimit-limit | Celkový příděl uvnitř okna. |
| x-ratelimit-remaining | Kolik zbývá v tomto okně. |
| x-ratelimit-reset | Počet sekund do obnovení přídělu. |
| retry-after | Kolik sekund počkat před opakováním. Uvádí se pouze v odpovědi, která požadavek odmítla. |
Jakmile je limit překročen, požadavek se odmítne a odpověď uvede v sekundách, jak dlouho se má čekat. Opakování se provádí až po této době, ne okamžitě.
Formát chyby
Každá chyba se vrací ve stejné obálce: krátké pole s kódem, podle kterého se větví stroj, a pole s vysvětlením, které přečte člověk.
- errorKrátký kód, podle kterého se klient rozhoduje.
- messageVysvětlení toho, co se stalo.
| Stav | Pole s kódem | Co to znamená |
|---|---|---|
| 400 | Bad Request | Požadavek neodpovídá schématu. Vysvětlení uvádí pole, které chybí nebo je neplatné. |
| 401 | unauthenticated | Chybí platná identita: token nebyl odeslán, vypršel, nebo se neověřil. |
| 404 | Not Found | Takový koncový bod neexistuje, nebo takový záznam neexistuje. |
| 429 | Too Many Requests | Byl překročen limit četnosti; odpověď uvádí, jak dlouho se má čekat. |
| 5xx | internal_error | Neočekávané selhání. Podrobnost se klientovi nepředává; zapisuje se do serverového protokolu. |
Stránkování
Koncové body vracející seznamy přijímají stejné dva parametry a vracejí stejné čítače, takže se stránkovací klient nepíše znovu pro každý koncový bod.
- limitKolik záznamů má stránka obsahovat. Nejméně jeden, nejvíce dvě stě; padesát, pokud není nastaveno.
- offsetKolik záznamů přeskočit. Začíná na nule.
- totalKolik záznamů celkem odpovídá filtrům.
- countKolik záznamů tato odpověď skutečně nese.
Odpověď rovněž vrací limit a offset, které použila; klient tak svou pozici čte z odpovědi, místo aby ji odhadoval.
Výměna dat a webhooky
Režim výměny je nastavení, ne samostatný produkt: každá registrovaná aplikace nese režim, v němž pracuje, ve svém vlastním záznamu.
| Režim | Co to znamená |
|---|---|
| Jednosměrně — ven | Optifora data zveřejňuje; druhá strana je čte nebo odebírá události. |
| Jednosměrně — dovnitř | Druhá strana data odesílá; Optifora je ověří a zapíše. |
| Obousměrně | Zapisují obě strany; pravidlo pro řešení konfliktu je stanoveno předem. |
| Navázání spojení | Každý přenos otevírá relaci: nabídka, ověření, schválení, přenos a potvrzení. Potvrzení zůstává oběma stranám. |
- Události se odesílají venWebhook odešle událost na adresu zpětného volání, kterou registrovaná aplikace ohlásila. Událost, kterou nelze doručit, zůstává ve frontě a doručení se opakuje; nikdy se tiše nezahodí.
- Stejný požadavek nezapisuje dvakrátZápisový požadavek nese klíč idempotence. Druhý požadavek se stejným klíčem už žádný další záznam nevytvoří.
- Každé volání se měříKdo volal, kdy, s jakým rozsahem a s jakým výsledkem — vše se zaznamenává. Tentýž záznam odpovídá jak na ladění, tak na otázku, kdo tato data stáhl.
- Naše vlastní aplikace používají tytéž dveřeŽádná privilegovaná druhá cesta neexistuje. Naše vlastní integrace je důkazem toho, jaké rozhraní potká vnější vývojář.
Datový model výměnné vrstvy je hotový; její koncové body zatím nejsou zveřejněny. Až budou, odkáže tato část na jejich záznamy v referenci.
Referenční dokumenty
Reference se nepíše ručně; generuje se ze schémat koncových bodů. Jak každý koncový bod předá své schéma, dokument se sám doplňuje, takže se dokument a chování nemohou rozejít.
- Dnes: v přípravěSchémata se doplňují modul po modulu. Než bude dokument zveřejněn, bude v něm vidět požadavek i odpověď každého koncového bodu.
- Zveřejní se dva formátyStrojově čitelný dokument OpenAPI a referenční stránka vytvořená z téhož dokumentu a prohlížitelná v prohlížeči.
- Přístup je odstupňovanýPřehled je otevřený komukoli. Úplná reference může být za dokumentačním tokenem vydaným registrovanému integrátorovi; produkční klíče a adresy zpětných volání nejsou vůbec věcí dokumentace — patří k záznamu aplikace.
- Standard adresZveřejňují se dva referenční dokumenty a jejich adresy jsou pevné: client-api.optifora.com/docs je otevřený, admin-api.optifora.com/docs vyžaduje oprávnění a je uzavřený navenek. Ani jeden dnes není v provozu; odkazy se do této části doplní, jakmile budou.
Pokud je váš integrační záměr už jasný, napište nám z kontaktní stránky: budete mezi prvními, kdo se dozví o otevření rozhraní.
Máte konkrétní požadavek?
Tyto stránky vysvětlují, jak proces podpory funguje. Máte-li požadavek nebo dotaz, napište nám z kontaktní stránky.
Přejít na kontaktní stránku