Sådan virker Optifora-API'et
Denne side beskriver API'ets form: hvordan identitet bevises, hvordan versioner rykker frem, hvilke grænser en forespørgsel holder sig inden for, hvordan en fejl ser ud, og hvordan data udveksles med omverdenen.
Produktet er under udvikling, og API-fladen bliver stadig færdiggjort. Et referencedokument for endepunkterne udgives særskilt; denne side bærer hverken adresse eller eksempelkald, kun mekanikken.
Godkendelse
Hver forespørgsel tilhører enten en person eller en registreret applikation. En forespørgsel uden identitet, der når et beskyttet endepunkt, kommer tilbage som ugodkendt.
- Bearer-tokenAdgangstokenet rejser i forespørgslens autorisationshoved. Det er signeret, og det siger kun, hvem forespørgslen tilhører.
- Kort levetidEt adgangstoken udløber efter et tidsrum målt i minutter; længden er en driftsindstilling og er som standard tredive minutter.
- Fornyelse og rotationEn session forlænges med et fornyelsestoken, og hver forlængelse udsteder et nyt par. Hvis et brugt fornyelsestoken fremvises anden gang, tilbagekaldes alle sessioner for den pågældende person.
- Rettigheder bages ikke ind i tokenetTokenet bærer kun identitet; hvad en person må se, spørges databasen om ved hver forespørgsel. En tilladelse, der trækkes tilbage, holder derfor op med at virke, før tokenet i hånden udløber.
- IntegratornøgleEn registreret applikation forbinder med sin egen nøgle. Den rene værdi vises én gang, ved oprettelsen; det, der gemmes, er dens hashværdi og det ikke-hemmelige præfiks, som gør en nøgle genkendelig.
- Organisationen giver adgangenHvor udbredt en applikation end er, ser den ikke én eneste række uden en tilladelse, som organisationen har registreret. Tilladelsen er dateret, afgrænset og kan tilbagekaldes.
Versionering
- Versionen ligger i stienEndepunkter udgives bag et versionspræfiks; dagens flade er version et.
- En brydende ændring åbner en ny stiEt eksisterende endepunkts kontrakt brydes ikke på stedet. En inkompatibel ændring udgives på en ny versionssti, mens den gamle bliver ved med at virke.
- Dokumentet oplyser sin egen versionReferencen bærer det versionsnummer, den er genereret ud fra; hvilken version du læser, besvares af dokumentet selv.
Miljøer og grænser
Referencen erklærer to miljøer: produktion og lokal udvikling. Rodadressen udleveres til en integrator sammen med nøglen; den udgives ikke på denne side.
- Liveness og readiness måles hver for sigÉt endepunkt siger, at processen kører; det andet sender en rigtig forespørgsel til databasen og bekræfter, at den kan nås. Kun det andet afgør, om der skal sendes trafik.
- Browseroprindelser er begrænset til en listeForespørgsler på tværs af oprindelser accepteres kun fra oprindelser, der er erklæret på forhånd; så længe listen er tom, afvises en browserforespørgsel på tværs af oprindelser.
- KropsgrænseEn forespørgselskrop må ikke overstige fem megabyte. Store mængder rejser som et masseoverførselsjob med sin egen statuspost, ikke som én enkelt forespørgsel.
- Hemmeligheder skrives ikke i loggenServerloggen gemmer hverken autorisationshoved, cookie, adgangskode eller personnummer.
Hastighedsgrænse
Grænsen gælder pr. adresse og pr. minut. Standarden er 120 forespørgsler i minuttet og sættes ved idriftsættelsen. Det resterende oplyses i hoveder på hvert svar.
| Svarhoved | Hvad det siger |
|---|---|
| x-ratelimit-limit | Den samlede kvote inden for vinduet. |
| x-ratelimit-remaining | Hvad der er tilbage i dette vindue. |
| x-ratelimit-reset | Sekunder til kvoten fornys. |
| retry-after | Hvor mange sekunder der skal gå før et nyt forsøg. Findes kun i det svar, der afviste forespørgslen. |
Når grænsen er passeret, afvises forespørgslen, og svaret angiver i sekunder, hvor længe der skal ventes. Et nyt forsøg foretages efter det tidsrum, ikke med det samme.
Fejlformat
Enhver fejl kommer tilbage i den samme konvolut: et kort kodefelt, som maskinen forgrener sig efter, og et forklaringsfelt, som et menneske kan læse.
- errorDen korte kode, som klienten forgrener sig efter.
- messageForklaringen på, hvad der skete.
| Status | Kodefelt | Hvad det betyder |
|---|---|---|
| 400 | Bad Request | Forespørgslen svarer ikke til skemaet. Forklaringen navngiver det felt, der mangler eller er ugyldigt. |
| 401 | unauthenticated | Der er ingen gyldig identitet: intet token blev sendt, det er udløbet, eller det kunne ikke verificeres. |
| 404 | Not Found | Intet sådant endepunkt eller ingen sådan post. |
| 429 | Too Many Requests | Hastighedsgrænsen blev overskredet; svaret angiver, hvor længe der skal ventes. |
| 5xx | internal_error | En uventet fejl. Detaljen gives ikke til klienten; den skrives i serverloggen. |
Sideinddeling
Endepunkter, der returnerer lister, tager de samme to parametre og returnerer de samme tællere, så en klient, der bladrer, ikke skal skrives om for hvert endepunkt.
- limitHvor mange poster en side skal rumme. Mindst én, højst to hundrede; halvtreds når intet er sat.
- offsetHvor mange poster der skal springes over. Begynder ved nul.
- totalHvor mange poster der i alt matcher filtrene.
- countHvor mange poster dette svar rent faktisk bærer.
Svaret gentager også den grænse og forskydning, det brugte; klienten læser sin position i svaret i stedet for at gætte den.
Dataudveksling og webhooks
Udvekslingstilstanden er en indstilling, ikke et separat produkt: hver registreret applikation bærer den tilstand, den arbejder i, på sin egen post.
| Tilstand | Hvad det betyder |
|---|---|
| Envejs — udgående | Optifora udgiver data; den anden side læser dem eller abonnerer på hændelser. |
| Envejs — indgående | Den anden side sender data ind; Optifora validerer dem og skriver dem. |
| Tovejs | Begge sider skriver; konfliktreglen er fastlagt på forhånd. |
| Håndtryk | Hver overførsel åbner en session: tilbud, verifikation, godkendelse, overførsel og kvittering. Kvitteringen bliver hos begge sider. |
- Hændelser sendes udEn webhook sender hændelsen til den tilbagekaldsadresse, den registrerede applikation har oplyst. En hændelse, der ikke kan leveres, bliver i køen og forsøges igen; den forsvinder aldrig i stilhed.
- Den samme forespørgsel skriver ikke to gangeEn skriveforespørgsel bærer en idempotensnøgle. En anden forespørgsel med samme nøgle opretter ingen anden post.
- Hvert kald målesHvem der kaldte, hvornår, med hvilket omfang og med hvilket resultat — det hele registreres. Den samme post besvarer både fejlsøgning og spørgsmålet om, hvem der hentede disse data.
- Vores egne apps bruger den samme dørDer findes ingen privilegeret anden vej. Vores egen integration er beviset på den flade, en udvikler udefra møder.
Datamodellen for udvekslingslaget er på plads; dens endepunkter er endnu ikke udgivet. Når de er, vil dette afsnit linke til deres poster i referencen.
Referencedokumenter
Referencen skrives ikke i hånden; den genereres ud fra endepunkternes skemaer. Efterhånden som hvert endepunkt afleverer sit skema, fyldes dokumentet af sig selv, så dokumentet og adfærden ikke kan glide fra hinanden.
- I dag: under forberedelseSkemaerne rykker frem modul for modul. Inden dokumentet udgives, vil hvert endepunkts forespørgsel og svar være synlige i det.
- To formater bliver udgivetEt maskinlæsbart OpenAPI-dokument og en referenceside, der er trukket ud af netop det dokument og kan gennemses i en browser.
- Adgangen er trinvisOversigten er åben for alle. Den fulde reference kan ligge bag et dokumentationstoken, som gives til en registreret integrator; produktionsnøgler og tilbagekaldsadresser er slet ikke et dokumentationsanliggende — de hører til applikationens post.
- AdressestandardTo referencer udgives, og deres adresser ligger fast: client-api.optifora.com/docs er åben, admin-api.optifora.com/docs kræver godkendelse og er lukket udadtil. Ingen af dem er i drift i dag; linkene tilføjes dette afsnit, når de er.
Er din integrationsplan allerede klar, så skriv til os fra kontaktsiden: du bliver blandt de første, der får besked, når fladen åbner.
Har du en bestemt anmodning?
Disse sider forklarer, hvordan supportforløbet virker. Har du en anmodning eller et spørgsmål, så skriv til os fra kontaktsiden.
Gå til kontaktsiden