Slik virker Optifora-API-et
Denne siden beskriver formen på API-et: hvordan identitet bevises, hvordan versjoner går videre, hvilke grenser en forespørsel holder seg innenfor, hvordan en feil ser ut, og hvordan data utveksles med omverdenen.
Produktet er under utvikling, og API-flaten fullføres fortsatt. Et referansedokument for endepunktene publiseres separat; denne siden har verken adresse eller eksempelkall, bare mekanikken.
Autentisering
Hver forespørsel tilhører enten en person eller en registrert applikasjon. En forespørsel uten identitet som når et beskyttet endepunkt, kommer tilbake som uautentisert.
- Bearer-tokenTilgangstokenet følger med i forespørselens autorisasjonshode. Det er signert, og det sier bare hvem forespørselen tilhører.
- Kort levetidEt tilgangstoken utløper etter et tidsrom målt i minutter; lengden er en driftsinnstilling og er som standard tretti minutter.
- Fornyelse og rotasjonEn økt forlenges med et fornyelsestoken, og hver forlengelse utsteder et nytt par. Blir et brukt fornyelsestoken lagt fram en gang til, tilbakekalles alle økter for vedkommende.
- Tilganger bakes ikke inn i tokenetTokenet bærer bare identitet; hva en person har lov til å se, spørres databasen om ved hver forespørsel. En tilgang som trekkes tilbake, slutter derfor å virke før tokenet du har i hånden utløper.
- IntegratornøkkelEn registrert applikasjon kobler seg til med sin egen nøkkel. Klarteksten vises én gang, ved opprettelsen; det som lagres er kontrollsummen og det ikke-hemmelige prefikset som gjør at en nøkkel kan gjenkjennes.
- Virksomheten gir tilgangenUansett hvor utbredt en applikasjon er, ser den ikke én eneste rad uten en tildeling registrert av virksomheten. Tildelingen er datert, avgrenset og kan trekkes tilbake.
Versjonering
- Versjonen ligger i stienEndepunkter publiseres bak et versjonsprefiks; dagens flate er versjon én.
- En bruddendring åpner en ny stiKontrakten til et eksisterende endepunkt brytes ikke på stedet. En ikke-kompatibel endring publiseres på en ny versjonssti mens den gamle fortsetter å virke.
- Dokumentet oppgir sin egen versjonReferansen bærer versjonsnummeret den ble generert fra; hvilken versjon du leser, svarer dokumentet selv på.
Miljøer og grenser
Referansen erklærer to miljøer: produksjon og lokal utvikling. Rotadressen overleveres til en integrator sammen med nøkkelen; den publiseres ikke på denne siden.
- Liveness og readiness måles hver for segEtt endepunkt sier at prosessen er oppe; det andre sender en reell spørring til databasen og bekrefter at den er tilgjengelig. Bare det andre avgjør om trafikk skal sendes.
- Nettleseropphav er begrenset til en listeForespørsler på tvers av opphav godtas bare fra opphav som er erklært på forhånd; så lenge listen er tom, avvises en nettleserforespørsel på tvers av opphav.
- Grense for kroppsstørrelseEn forespørselskropp kan ikke overstige fem megabyte. Store sett går som en samleoverføringsjobb med sin egen statuspost, ikke som én enkelt forespørsel.
- Hemmeligheter skrives ikke til loggenTjenerloggen tar vare på verken autorisasjonshode, informasjonskapsel, passord eller fødselsnummer.
Hastighetsgrense
Grensen gjelder per adresse og per minutt. Standarden er 120 forespørsler i minuttet og settes ved utrulling. Hva som er igjen, rapporteres i hoder på hvert svar.
| Svarhode | Hva det sier |
|---|---|
| x-ratelimit-limit | Den samlede kvoten innenfor vinduet. |
| x-ratelimit-remaining | Hva som er igjen i dette vinduet. |
| x-ratelimit-reset | Sekunder til kvoten fornyes. |
| retry-after | Hvor mange sekunder før et nytt forsøk. Finnes bare på svaret som avviste forespørselen. |
Når grensen er passert, avvises forespørselen, og svaret sier hvor lenge du skal vente, i sekunder. Et nytt forsøk gjøres etter den tiden, ikke med én gang.
Feilformat
Hver feil kommer tilbake i den samme konvolutten: et kort kodefelt som maskinen forgrener på, og et forklaringsfelt som et menneske kan lese.
- errorDen korte koden klienten tar avgjørelsen sin på.
- messageForklaringen på hva som skjedde.
| Status | Kodefelt | Hva det betyr |
|---|---|---|
| 400 | Bad Request | Forespørselen samsvarer ikke med skjemaet. Forklaringen navngir feltet som mangler eller er ugyldig. |
| 401 | unauthenticated | Det finnes ingen gyldig identitet: ingen token ble sendt, den er utløpt, eller den lot seg ikke verifisere. |
| 404 | Not Found | Ikke noe slikt endepunkt, eller ingen slik post. |
| 429 | Too Many Requests | Hastighetsgrensen ble overskredet; svaret sier hvor lenge du skal vente. |
| 5xx | internal_error | En uventet feil. Detaljen overleveres ikke til klienten; den skrives til tjenerloggen. |
Sidedeling
Endepunkter som returnerer lister, tar de samme to parameterne og returnerer de samme tellerne, slik at en klient som blar, ikke må skrives om for hvert endepunkt.
- limitHvor mange poster en side skal romme. Minst én, høyst to hundre; femti når verdien ikke er satt.
- offsetHvor mange poster som skal hoppes over. Starter på null.
- totalHvor mange poster som treffer filtrene til sammen.
- countHvor mange poster dette svaret faktisk bærer.
Svaret gjentar også grensen og forskyvningen det brukte; klienten leser posisjonen sin av svaret i stedet for å gjette den.
Datautveksling og webhooks
Utvekslingsmodusen er en innstilling, ikke et eget produkt: hver registrerte applikasjon bærer modusen den arbeider i på sin egen post.
| Modus | Hva det betyr |
|---|---|
| Enveis — utgående | Optifora publiserer data; den andre siden leser dem eller abonnerer på hendelser. |
| Enveis — innkommende | Den andre siden sender data; Optifora validerer dem og skriver dem. |
| Toveis | Begge sider skriver; konfliktregelen er definert på forhånd. |
| Håndtrykk | Hver overføring åpner en økt: tilbud, verifisering, godkjenning, overføring og kvittering. Kvitteringen blir værende hos begge sider. |
- Hendelser sendes utEn webhook sender hendelsen til tilbakekallsadressen den registrerte applikasjonen har oppgitt. En hendelse som ikke kan leveres, blir stående i kø og prøves på nytt; den forkastes aldri i stillhet.
- Den samme forespørselen skriver ikke to gangerEn skriveforespørsel bærer en idempotensnøkkel. En ny forespørsel med samme nøkkel oppretter ingen ny post.
- Hvert kall målesHvem som kalte, når, med hvilket omfang og med hvilket resultat — alt sammen registreres. Den samme posten svarer både på feilsøking og på spørsmålet om hvem som hentet disse dataene.
- Våre egne apper bruker den samme dørenDet finnes ingen privilegert andre vei. Vår egen integrasjon er beviset på flaten en utenforstående utvikler møter.
Datamodellen for utvekslingslaget er på plass; endepunktene er ennå ikke publisert. Når de er det, vil denne delen lenke til oppføringene deres i referansen.
Referansedokumenter
Referansen skrives ikke for hånd; den genereres fra endepunktenes skjemaer. Etter hvert som hvert endepunkt overleverer skjemaet sitt, fylles dokumentet ut av seg selv, slik at dokumentet og oppførselen ikke kan sprike.
- I dag: under forberedelseSkjemaene flyttes modul for modul. Før dokumentet publiseres, vil hvert endepunkts forespørsel og svar være synlig i det.
- To formater publiseresEt maskinlesbart OpenAPI-dokument, og en referanseside hentet fra det samme dokumentet og lesbar i en nettleser.
- Tilgangen er trinndeltOversikten er åpen for alle. Den fullstendige referansen kan ligge bak et dokumentasjonstoken som gis til en registrert integrator; produksjonsnøkler og tilbakekallsadresser er overhodet ikke et dokumentasjonsanliggende — de hører til applikasjonens egen post.
- AdressestandardTo referanser publiseres, og adressene deres er faste: client-api.optifora.com/docs er åpen, admin-api.optifora.com/docs krever autorisasjon og er lukket utad. Ingen av dem er i drift i dag; lenkene legges inn i denne delen når de er det.
Er integrasjonsplanen din allerede klar, skriv til oss fra kontaktsiden: du blir blant de første som får beskjed når flaten åpnes.
Har du en bestemt forespørsel?
Disse sidene forklarer hvordan støtteprosessen virker. Har du en forespørsel eller et spørsmål, skriv til oss fra kontaktsiden.
Gå til kontaktsiden