Cum funcționează API-ul Optifora
Această pagină descrie forma API-ului: cum se dovedește identitatea, cum înaintează versiunile, în ce limite rămâne o cerere, cum arată o eroare și cum se schimbă datele cu exteriorul.
Produsul este în dezvoltare, iar suprafața API este încă în curs de completare. Un document de referință pentru punctele de acces va fi publicat separat; această pagină nu conține nicio adresă și niciun apel de exemplu, ci doar mecanica.
Autentificare
Fiecare cerere aparține fie unei persoane, fie unei aplicații înregistrate. O cerere fără identitate care ajunge la un punct protejat se întoarce ca neautentificată.
- Jeton BearerJetonul de acces călătorește în antetul de autorizare al cererii. Este semnat și spune doar cui îi aparține cererea.
- Durată scurtăUn jeton de acces expiră după un interval măsurat în minute; durata este o setare de instalare și este implicit de treizeci de minute.
- Reîmprospătare și rotațieO sesiune se prelungește cu un jeton de reîmprospătare, iar fiecare prelungire emite o pereche nouă. Dacă un jeton de reîmprospătare deja consumat este prezentat a doua oară, toate sesiunile persoanei respective sunt revocate.
- Permisiunile nu sunt înscrise în jetonJetonul poartă doar identitatea; ce anume poate vedea o persoană este întrebat bazei de date la fiecare cerere. Astfel, o permisiune retrasă încetează să funcționeze înainte ca jetonul aflat în mână să expire.
- Cheia integratoruluiO aplicație înregistrată se conectează cu cheia sa proprie. Valoarea în clar este afișată o singură dată, la creare; ceea ce se păstrează este amprenta ei și prefixul nesecret care permite recunoașterea cheii.
- Organizația acordă accesulOricât de răspândită ar fi o aplicație, fără o autorizare consemnată de organizație nu vede niciun rând. Autorizarea este datată, limitată ca domeniu și revocabilă.
Versionare
- Versiunea se află în calePunctele de acces se publică în spatele unui prefix de versiune; suprafața de astăzi este versiunea unu.
- O modificare incompatibilă deschide o cale nouăContractul unui punct de acces existent nu se rupe pe loc. O modificare incompatibilă se publică pe o cale de versiune nouă, în timp ce cea veche continuă să funcționeze.
- Documentul își declară propria versiuneReferința poartă numărul versiunii din care a fost generată; la întrebarea ce versiune citiți răspunde documentul însuși.
Medii și limite
Referința declară două medii: producție și dezvoltare locală. Adresa rădăcină îi este predată integratorului împreună cu cheia sa; nu se publică pe această pagină.
- Funcționarea și disponibilitatea se măsoară separatUn punct de acces spune că procesul este pornit; al doilea trimite o interogare reală către baza de date și confirmă că este accesibilă. Doar al doilea decide dacă trebuie trimis trafic.
- Originile de browser sunt limitate la o listăCererile din alte origini sunt acceptate doar de la originile declarate în prealabil; cât timp lista este goală, o cerere de browser din altă origine este refuzată.
- Limita corpuluiCorpul unei cereri nu poate depăși cinci megaocteți. Seturile mari călătoresc ca o sarcină de transfer în masă, cu propria înregistrare de stare, nu ca o singură cerere.
- Secretele nu se scriu în jurnalJurnalul serverului nu păstrează niciun antet de autorizare, niciun cookie, nicio parolă și niciun cod numeric personal.
Limita de ritm
Limita se aplică pe adresă și pe minut. Valoarea implicită este de 120 de cereri pe minut și se stabilește la instalare. Cât a rămas se raportează prin antete la fiecare răspuns.
| Antet de răspuns | Ce spune |
|---|---|
| x-ratelimit-limit | Alocarea totală în interiorul ferestrei. |
| x-ratelimit-remaining | Cât a rămas în această fereastră. |
| x-ratelimit-reset | Secunde până la reînnoirea alocării. |
| retry-after | Câte secunde până la o nouă încercare. Prezent doar în răspunsul care a refuzat cererea. |
Odată depășită limita, cererea este refuzată, iar răspunsul spune cât trebuie așteptat, în secunde. O nouă încercare se face după acel timp, nu imediat.
Formatul erorii
Fiecare eroare se întoarce în același plic: un câmp de cod scurt după care se ramifică mașina și un câmp de explicație pe care îl citește omul.
- errorCodul scurt după care decide clientul.
- messageExplicația a ceea ce s-a întâmplat.
| Stare | Câmpul de cod | Ce înseamnă |
|---|---|---|
| 400 | Bad Request | Cererea nu corespunde schemei. Explicația numește câmpul lipsă sau invalid. |
| 401 | unauthenticated | Nu există o identitate validă: nu s-a trimis niciun jeton, a expirat sau nu s-a verificat. |
| 404 | Not Found | Nu există un asemenea punct de acces sau nu există o asemenea înregistrare. |
| 429 | Too Many Requests | Limita de ritm a fost depășită; răspunsul spune cât trebuie așteptat. |
| 5xx | internal_error | O defecțiune neașteptată. Detaliul nu este predat clientului; se scrie în jurnalul serverului. |
Paginare
Punctele de acces care returnează liste primesc aceiași doi parametri și returnează aceiași contori, astfel încât un client de paginare nu se rescrie pentru fiecare punct de acces.
- limitCâte înregistrări să conțină o pagină. Cel puțin una, cel mult două sute; cincizeci când nu este setat.
- offsetCâte înregistrări se sar. Începe de la zero.
- totalCâte înregistrări corespund în total filtrelor.
- countCâte înregistrări poartă efectiv acest răspuns.
Răspunsul repetă și limita și decalajul pe care le-a folosit; clientul își citește poziția din răspuns, în loc să o ghicească.
Schimb de date și webhookuri
Modul de schimb este o setare, nu un produs separat: fiecare aplicație înregistrată poartă pe propria înregistrare modul în care lucrează.
| Mod | Ce înseamnă |
|---|---|
| Într-un singur sens — spre exterior | Optifora publică datele; cealaltă parte le citește sau se abonează la evenimente. |
| Într-un singur sens — spre interior | Cealaltă parte împinge datele; Optifora le validează și le scrie. |
| În ambele sensuri | Ambele părți scriu; regula de conflict este definită dinainte. |
| Strângere de mână | Fiecare transfer deschide o sesiune: ofertă, verificare, aprobare, transfer și confirmare de primire. Confirmarea rămâne la ambele părți. |
- Evenimentele sunt împinse spre exteriorUn webhook trimite evenimentul către adresa de retur declarată de aplicația înregistrată. Un eveniment care nu poate fi livrat rămâne în coadă și se reîncearcă; nu se pierde niciodată în tăcere.
- Aceeași cerere nu scrie de două oriO cerere de scriere poartă o cheie de idempotență. O a doua cerere cu aceeași cheie nu creează o a doua înregistrare.
- Fiecare apel este măsuratCine a apelat, când, cu ce domeniu și cu ce rezultat — totul se consemnează. Aceeași înregistrare răspunde și la depanare, și la întrebarea cine a extras aceste date.
- Aplicațiile noastre folosesc aceeași ușăNu există o a doua cale privilegiată. Propria noastră integrare este dovada suprafeței pe care o întâlnește un dezvoltator din exterior.
Modelul de date al stratului de schimb este pus la punct; punctele lui de acces nu sunt încă publicate. Când vor fi, această secțiune va trimite la intrările lor din referință.
Documente de referință
Referința nu se scrie de mână; se generează din schemele punctelor de acces. Pe măsură ce fiecare punct de acces își predă schema, documentul se completează de la sine, astfel încât documentul și comportamentul nu se pot îndepărta unul de altul.
- Astăzi: în pregătireSchemele avansează modul cu modul. Înainte de publicarea documentului, cererea și răspunsul fiecărui punct de acces vor fi vizibile în el.
- Se vor publica două formateUn document OpenAPI lizibil de mașină și o pagină de referință generată din același document, care poate fi parcursă în browser.
- Accesul are treptePrezentarea generală este deschisă oricui. Referința completă poate sta în spatele unui jeton de documentație acordat unui integrator înregistrat; cheile de producție și adresele de retur nu sunt deloc o chestiune de documentație — ele aparțin înregistrării aplicației.
- Standardul de adresăSunt publicate două referințe, iar adresele lor sunt fixe: client-api.optifora.com/docs este deschisă, admin-api.optifora.com/docs cere autorizare și este închisă spre exterior. Niciuna nu este activă astăzi; legăturile vor fi adăugate în această secțiune atunci când vor fi.
Dacă planul dumneavoastră de integrare este deja clar, scrieți-ne din pagina de contact: veți fi printre primii anunțați când se deschide suprafața.
Aveți o cerere anume?
Aceste pagini explică felul în care funcționează procesul de asistență. Dacă aveți o cerere sau o întrebare, scrieți-ne din pagina de contact.
Mergeți la pagina de contact