Så fungerar Optiforas API
Den här sidan beskriver API:ets form: hur identitet bevisas, hur versioner går framåt, vilka gränser en begäran håller sig inom, hur ett fel ser ut och hur data utbyts med omvärlden.
Produkten är under utveckling och API-ytan håller fortfarande på att färdigställas. Ett referensdokument för slutpunkterna publiceras separat; den här sidan innehåller varken adress eller exempelanrop, bara mekaniken.
Autentisering
Varje begäran tillhör antingen en person eller en registrerad applikation. En begäran utan identitet som når en skyddad slutpunkt kommer tillbaka som oautentiserad.
- Bearer-tokenÅtkomsttoken färdas i begärans authorization-huvud. Den är signerad och säger bara vem begäran tillhör.
- Kort livslängdEn åtkomsttoken löper ut efter en tid som mäts i minuter; längden är en driftsinställning och är trettio minuter som standard.
- Förnyelse och rotationEn session förlängs med en förnyelsetoken, och varje förlängning ger ut ett nytt par. Om en redan förbrukad förnyelsetoken visas upp en andra gång återkallas samtliga sessioner för den personen.
- Behörigheter bakas inte in i tokenToken bär endast identitet; vad en person får se frågas databasen om vid varje begäran. En behörighet som dras tillbaka slutar därför fungera innan den token du har i handen löper ut.
- IntegratörsnyckelEn registrerad applikation ansluter med sin egen nyckel. Klartextvärdet visas en enda gång, när nyckeln skapas; det som lagras är dess kondensat och det icke-hemliga prefix som gör att en nyckel kan kännas igen.
- Organisationen beviljar åtkomstenHur spridd en applikation än är ser den inte en enda rad utan ett medgivande som organisationen registrerat. Medgivandet är daterat, avgränsat och återkalleligt.
Versionshantering
- Versionen ligger i sökvägenSlutpunkter publiceras bakom ett versionsprefix; dagens yta är version ett.
- En brytande ändring öppnar en ny sökvägEn befintlig slutpunkts kontrakt bryts inte på plats. En inkompatibel ändring publiceras på en ny versionssökväg medan den gamla fortsätter att fungera.
- Dokumentet anger sin egen versionReferensen bär det versionsnummer den genererades ur; vilken version du läser besvaras av dokumentet självt.
Miljöer och gränser
Referensen deklarerar två miljöer: produktion och lokal utveckling. Rotadressen lämnas till en integratör tillsammans med nyckeln; den publiceras inte på den här sidan.
- Liveness och readiness mäts var för sigEn slutpunkt säger att processen är igång; den andra skickar en verklig fråga till databasen och bekräftar att den går att nå. Bara den andra avgör om trafik ska skickas dit.
- Webbläsarursprung begränsas till en listaKorsursprungsbegäranden accepteras endast från ursprung som deklarerats i förväg; så länge listan är tom avvisas en korsursprungsbegäran från webbläsare.
- Storleksgräns för kroppenEn begärans kropp får inte överstiga fem megabyte. Stora mängder färdas som ett massöverföringsjobb med egen statuspost, inte som en enda begäran.
- Hemligheter skrivs inte till loggenServerloggen sparar varken authorization-huvud, kaka, lösenord eller personnummer.
Hastighetsgräns
Gränsen gäller per adress och per minut. Standard är 120 begäranden i minuten och sätts vid driftsättningen. Det som återstår rapporteras i huvuden på varje svar.
| Svarshuvud | Vad det säger |
|---|---|
| x-ratelimit-limit | Hela kvoten inom fönstret. |
| x-ratelimit-remaining | Vad som återstår i det här fönstret. |
| x-ratelimit-reset | Sekunder tills kvoten förnyas. |
| retry-after | Hur många sekunder innan ett nytt försök. Finns bara i det svar som avvisade begäran. |
När gränsen passerats avvisas begäran och svaret anger hur länge du ska vänta, i sekunder. Ett nytt försök görs efter den tiden, inte omedelbart.
Felformat
Varje fel kommer tillbaka i samma kuvert: ett kort kodfält som maskinen kan förgrena på, och ett förklaringsfält som en människa kan läsa.
- errorDen korta koden som klienten fattar sitt beslut på.
- messageFörklaringen av vad som hände.
| Status | Kodfält | Vad det betyder |
|---|---|---|
| 400 | Bad Request | Begäran stämmer inte med schemat. Förklaringen namnger fältet som saknas eller är ogiltigt. |
| 401 | unauthenticated | Det finns ingen giltig identitet: ingen token skickades, den har löpt ut eller den gick inte att verifiera. |
| 404 | Not Found | Ingen sådan slutpunkt, eller ingen sådan post. |
| 429 | Too Many Requests | Hastighetsgränsen överskreds; svaret anger hur länge du ska vänta. |
| 5xx | internal_error | Ett oväntat fel. Detaljen lämnas inte till klienten; den skrivs till serverloggen. |
Sidindelning
Slutpunkter som returnerar listor tar samma två parametrar och returnerar samma räknare, så en klient som bläddrar behöver inte skrivas om för varje slutpunkt.
- limitHur många poster en sida ska rymma. Minst en, högst tvåhundra; femtio när inget anges.
- offsetHur många poster som ska hoppas över. Börjar på noll.
- totalHur många poster som totalt matchar filtren.
- countHur många poster det här svaret faktiskt bär.
Svaret upprepar också den limit och offset det använde; klienten läser sin position ur svaret i stället för att gissa den.
Datautbyte och webhookar
Utbytesläget är en inställning, inte en separat produkt: varje registrerad applikation bär det läge den arbetar i på sin egen post.
| Läge | Vad det betyder |
|---|---|
| Envägs — utgående | Optifora publicerar data; motparten läser den eller prenumererar på händelser. |
| Envägs — inkommande | Motparten skickar in data; Optifora validerar den och skriver den. |
| Tvåvägs | Båda sidor skriver; konfliktregeln är definierad i förväg. |
| Handskakning | Varje överföring öppnar en session: erbjudande, verifiering, godkännande, överföring och kvitto. Kvittot stannar hos båda sidor. |
- Händelser skickas utEn webhook skickar händelsen till den återanropsadress som den registrerade applikationen deklarerat. En händelse som inte kan levereras stannar i kön och försöks igen; den släpps aldrig tyst.
- Samma begäran skriver inte två gångerEn skrivbegäran bär en idempotensnyckel. En andra begäran med samma nyckel skapar ingen andra post.
- Varje anrop mätsVem som anropade, när, med vilken omfattning och med vilket resultat — allt registreras. Samma post besvarar både felsökningen och frågan om vem som hämtade de här uppgifterna.
- Våra egna appar går genom samma dörrDet finns ingen privilegierad andra väg. Vår egen integration är beviset på den yta en utomstående utvecklare möter.
Datamodellen för utbytesskiktet är på plats; dess slutpunkter är ännu inte publicerade. När de är det kommer det här avsnittet att länka till deras poster i referensen.
Referensdokument
Referensen skrivs inte för hand; den genereras ur slutpunkternas scheman. Allt eftersom varje slutpunkt lämnar över sitt schema fylls dokumentet i av sig självt, så dokumentet och beteendet kan inte glida isär.
- I dag: under förberedelseScheman flyttas över modul för modul. Innan dokumentet publiceras kommer varje slutpunkts begäran och svar att synas i det.
- Två format kommer att publicerasEtt maskinläsbart OpenAPI-dokument, och en referenssida som hämtas ur samma dokument och går att bläddra i en webbläsare.
- Åtkomsten är nivåindeladÖversikten är öppen för alla. Den fullständiga referensen kan ligga bakom en dokumentationstoken som ges till en registrerad integratör; produktionsnycklar och återanropsadresser är över huvud taget ingen dokumentationsfråga — de hör till applikationsposten.
- AdresstandardTvå referenser publiceras och deras adresser är fasta: client-api.optifora.com/docs är öppen, admin-api.optifora.com/docs kräver behörighet och är stängd utåt. Ingen av dem är i drift i dag; länkarna läggs till i det här avsnittet när de är det.
Om din integrationsplan redan är klar, skriv till oss från kontaktsidan: du blir bland de första som får veta när ytan öppnar.
Har du ett särskilt önskemål?
De här sidorna förklarar hur supportprocessen fungerar. Har du ett önskemål eller en fråga, skriv till oss från kontaktsidan.
Gå till kontaktsidan