Kako radi Optifora API
Ova stranica opisuje oblik API-ja: kako se dokazuje identitet, kako se pomiču verzije, unutar kojih ograničenja zahtjev ostaje, kako izgleda pogreška i kako se podaci razmjenjuju s vanjskim svijetom.
Proizvod je u razvoju i površina API-ja se još dovršava. Referentni dokument za krajnje točke bit će objavljen zasebno; ova stranica ne nosi ni adresu ni primjer poziva, samo mehaniku.
Provjera identiteta
Svaki zahtjev pripada ili osobi ili registriranoj aplikaciji. Zahtjev bez identiteta koji stigne na zaštićenu krajnju točku vraća se neautenticiran.
- Bearer tokenPristupni token putuje u autorizacijskom zaglavlju zahtjeva. Potpisan je i govori samo kome zahtjev pripada.
- Kratak vijekPristupni token istječe nakon razdoblja mjerenog u minutama; duljina je postavka postavljanja i po zadanome iznosi trideset minuta.
- Obnova i rotacijaSjednica se produljuje tokenom za obnovu, a svako produljenje izdaje novi par. Ako se potrošeni token za obnovu predoči drugi put, opozivaju se sve sjednice te osobe.
- Ovlasti nisu ugrađene u tokenToken nosi samo identitet; što osoba smije vidjeti pita se bazu podataka pri svakom zahtjevu. Povučena ovlast zato prestaje djelovati prije nego što istekne token koji je u rukama.
- Integratorski ključRegistrirana aplikacija spaja se vlastitim ključem. Otvorena vrijednost prikazuje se jednom, pri stvaranju; pohranjuje se njezin sažetak i netajni predmetak po kojem se ključ prepoznaje.
- Organizacija odobrava pristupKoliko god aplikacija bila raširena, bez odobrenja koje je organizacija zabilježila ne vidi niti jedan redak. Odobrenje ima datum, opseg i može se opozvati.
Verzioniranje
- Verzija stoji u putanjiKrajnje točke objavljuju se iza predmetka verzije; današnja je površina verzija jedan.
- Nespojiva promjena otvara novu putanjuUgovor postojeće krajnje točke ne krši se na mjestu. Nespojiva promjena objavljuje se na novoj putanji verzije, dok stara i dalje radi.
- Dokument sam navodi svoju verzijuReferenca nosi broj verzije iz koje je stvorena; koju verziju čitate odgovara sam dokument.
Okruženja i ograničenja
Referenca navodi dva okruženja: proizvodno i lokalno razvojno. Korijenska adresa predaje se integratoru zajedno s njegovim ključem; ne objavljuje se na ovoj stranici.
- Živost i spremnost mjere se zasebnoJedna krajnja točka govori da proces radi; druga šalje pravi upit bazi podataka i potvrđuje da je dostupna. Samo druga odlučuje treba li slati promet.
- Preglednički izvori ograničeni su na popisZahtjevi s drugog izvora prihvaćaju se samo s izvora prijavljenih unaprijed; dok je popis prazan, preglednički zahtjev s drugog izvora se odbija.
- Ograničenje tijelaTijelo zahtjeva ne smije premašiti pet megabajta. Veliki skupovi putuju kao skupni posao prijenosa s vlastitim zapisom stanja, a ne kao jedan zahtjev.
- Tajne se ne zapisuju u zapisnikZapisnik poslužitelja ne čuva autorizacijsko zaglavlje, kolačić, lozinku ni osobni identifikacijski broj.
Ograničenje brzine
Ograničenje vrijedi po adresi i po minuti. Zadano je 120 zahtjeva u minuti i postavlja se pri postavljanju. Ono što preostaje javlja se u zaglavljima svakog odgovora.
| Zaglavlje odgovora | Što govori |
|---|---|
| x-ratelimit-limit | Ukupna dopuštena količina unutar prozora. |
| x-ratelimit-remaining | Koliko je preostalo u ovom prozoru. |
| x-ratelimit-reset | Sekunde do obnove dopuštene količine. |
| retry-after | Koliko sekundi do ponovnog pokušaja. Prisutno samo u odgovoru koji je zahtjev odbio. |
Kada se ograničenje premaši, zahtjev se odbija, a odgovor govori koliko treba pričekati, u sekundama. Ponovni pokušaj radi se nakon tog vremena, a ne odmah.
Oblik pogreške
Svaka se pogreška vraća u istoj omotnici: kratko polje koda po kojemu stroj grana i polje s objašnjenjem koje čovjek čita.
- errorKratki kod prema kojemu klijent odlučuje.
- messageObjašnjenje onoga što se dogodilo.
| Status | Polje koda | Što znači |
|---|---|---|
| 400 | Bad Request | Zahtjev ne odgovara shemi. Objašnjenje imenuje polje koje nedostaje ili nije valjano. |
| 401 | unauthenticated | Nema valjanog identiteta: token nije poslan, istekao je ili se nije potvrdio. |
| 404 | Not Found | Nema takve krajnje točke ili nema takvog zapisa. |
| 429 | Too Many Requests | Ograničenje brzine je premašeno; odgovor govori koliko treba pričekati. |
| 5xx | internal_error | Neočekivani kvar. Pojedinost se ne predaje klijentu; zapisuje se u zapisnik poslužitelja. |
Straničenje
Krajnje točke koje vraćaju popise primaju ista dva parametra i vraćaju iste brojače, pa se klijent za straničenje ne piše iznova za svaku krajnju točku.
- limitKoliko zapisa stranica treba sadržavati. Najmanje jedan, najviše dvjesto; pedeset kada nije postavljeno.
- offsetKoliko zapisa preskočiti. Počinje od nule.
- totalKoliko zapisa ukupno odgovara filtrima.
- countKoliko zapisa ovaj odgovor doista nosi.
Odgovor također ponavlja limit i offset koje je upotrijebio; klijent svoj položaj čita iz odgovora umjesto da ga pogađa.
Razmjena podataka i webhookovi
Način razmjene je postavka, a ne zaseban proizvod: svaka registrirana aplikacija nosi na vlastitom zapisu način u kojem radi.
| Način | Što znači |
|---|---|
| Jednosmjerno — prema van | Optifora objavljuje podatke; druga ih strana čita ili se pretplaćuje na događaje. |
| Jednosmjerno — prema unutra | Druga strana šalje podatke; Optifora ih provjerava i zapisuje. |
| Dvosmjerno | Obje strane pišu; pravilo sukoba određeno je unaprijed. |
| Rukovanje | Svaki prijenos otvara sjednicu: ponuda, provjera, odobrenje, prijenos i potvrda. Potvrda ostaje kod obiju strana. |
- Događaji se šalju prema vanWebhook šalje događaj na povratnu adresu koju je registrirana aplikacija prijavila. Događaj koji se ne može isporučiti ostaje u redu i pokušava se ponovno; nikada se ne odbacuje bez traga.
- Isti zahtjev ne piše dvaputZahtjev za pisanje nosi ključ idempotentnosti. Drugi zahtjev s istim ključem ne stvara drugi zapis.
- Svaki se poziv mjeriTko je pozvao, kada, s kojim opsegom i s kakvim ishodom — sve se to bilježi. Isti zapis odgovara i na otklanjanje pogrešaka i na pitanje tko je povukao te podatke.
- Naše aplikacije koriste ista vrataNe postoji povlaštena druga putanja. Naša vlastita integracija dokaz je površine na koju nailazi vanjski razvojni programer.
Podatkovni model sloja razmjene je postavljen; njegove krajnje točke još nisu objavljene. Kada budu, ovaj će odjeljak voditi na njihove stavke u referenci.
Referentni dokumenti
Referenca se ne piše ručno; stvara se iz shema krajnjih točaka. Kako svaka krajnja točka preda svoju shemu, dokument se sam popunjava, pa dokument i ponašanje ne mogu razići.
- Danas: u pripremiSheme se pomiču modul po modul. Prije objave dokumenta u njemu će biti vidljiv zahtjev i odgovor svake krajnje točke.
- Objavit će se dva oblikaStrojno čitljiv OpenAPI dokument i referentna stranica izvedena iz istog dokumenta, koja se pregledava u pregledniku.
- Pristup je stupnjevanPregled je otvoren svima. Cijela referenca može stajati iza dokumentacijskog tokena danog registriranom integratoru; proizvodni ključevi i povratne adrese uopće nisu stvar dokumentacije — pripadaju zapisu aplikacije.
- Standard adreseObjavljuju se dvije reference i njihove su adrese utvrđene: client-api.optifora.com/docs je otvorena, admin-api.optifora.com/docs traži ovlaštenje i zatvorena je prema van. Nijedna danas nije aktivna; poveznice će biti dodane u ovaj odjeljak kada budu.
Ako je vaš plan integracije već jasan, pišite nam sa stranice za kontakt: bit ćete među prvima obaviješteni kada se površina otvori.
Imate određen zahtjev?
Ove stranice objašnjavaju kako teče postupak podrške. Ako imate zahtjev ili pitanje, pišite nam sa stranice za kontakt.
Idite na stranicu za kontakt