API-integration

Ett API är ett löfte till någon annans kod. Den som bygger mot det kommer att lita på fältnamn, format och beteende, och kan göra det långt efter att de som byggde API:et har gått vidare. Därför börjar vi i kontraktet, inte i implementationen.

Vi har byggt mot många API:er vi inte styr över själva, bland annat ett stort antal spelleverantörer inom iGaming och en lång rad betallösningar. Varje leverantör har sitt eget sätt att autentisera, versionera och rapportera fel, och det är där tiden brukar gå.

Kontraktet först

En specifikation som checkas in tillsammans med koden går att granska i en pull request, och en ändring av ett fält syns i diffen innan den når produktion. Specifikationen låter också den som ska konsumera API:et börja bygga innan tjänsten finns, mot en mock som genereras ur den.

Bestäm versioneringen innan du behöver den

Bestäm redan från början vad som får ändras inom en version och vad som kräver en ny. En regel vi arbetar efter: inom en version får nya fält läggas till, men ett befintligt fält får inte byta betydelse, bli obligatoriskt eller försvinna. Nya fält i anropen måste gå att utelämna, för ett nytt obligatoriskt fält är en brytande ändring hur litet det än är. Allt annat får en ny version, med ett bestämt datum för när den gamla stängs.

Vad vi bygger in som standard

• Skrivande anrop som tål att skickas igen, så att ett nytt försök efter en timeout inte skapar en dubblett.
• Paginering från början. En lista utan övre gräns fungerar i test och växer i produktion tills den inte gör det.
• Riktiga statuskoder, inte ett felmeddelande i svaret med status 200.
• Tidpunkter i UTC när de betecknar ett exakt ögonblick. Datum, bokningar och perioder får den tidszon eller kalender de behöver för att tolkas rätt.
• Övervakning som larmar när ett flöde slutar leverera.

När behöver du inte ett kontrakt?

Kontraktet finns där så fort någon anropar tjänsten, nedskrivet eller inte. Frågan är hur mycket formalitet det förtjänar. Äger du båda sidor och kan ändra dem i samma release är en incheckad specifikation mest en formalitet. Behöver ett annat team få veta innan du byter namn på ett fält är den inte det. Ska API:et kopplas mot ett affärssystem hör det ihop med affärssystemintegration.