· 4 min
Fagstoff

API-integrasjoner som ikke ryker: sjekklisten før du kobler sammen to systemer

Integrasjoner er sjelden vanskelige å få til å virke første gang — de er vanskelige å få til å fortsette å virke. Fem spørsmål vi går gjennom før vi kobler to systemer sammen.

Vidd Studio

Denne artikkelen er for deg som skal koble produktet ditt til et system du ikke eier — et regnskapsprogram, en betalingsløsning, et CRM eller et offentlig register. Integrasjonen er sjelden vanskelig å få til å virke første gang. Den er vanskelig å få til å fortsette å virke. Her er de spørsmålene vi går gjennom før vi skriver en linje kode, og hva som skiller en integrasjon som tåler et halvt år i drift fra en som må reddes manuelt annenhver uke.

Den første versjonen virker alltid

En integrasjon som hentes opp i utviklingsmiljøet en tirsdag ettermiddag virker nesten alltid. API-et svarer raskt, dataene ser ut som dokumentasjonen sier, og ingen har endret noe siden i går. Problemene kommer senere, og de kommer sjelden som en tydelig feilmelding: en ordre som ikke ble overført, et beløp som ble bokført to ganger, en kunde som fikk to velkomst-e-poster, en synkronisering som stoppet for elleve dager siden uten at noen fikk beskjed.

Felles for dem er at de ikke skyldes dårlig kode i det vanlige tilfellet. De skyldes at det vanlige tilfellet ble det eneste som ble håndtert.

Fem spørsmål før du begynner

Vi går gjennom disse fem før vi bestemmer oss for hvordan en integrasjon skal bygges. De tar en halvtime, og de avgjør hvor mye arbeid integrasjonen blir å eie.

  • Hvem eier sannheten? Hvis både systemet ditt og det andre kan endre samme felt, må én av dem vinne — bestem hvilken før du bygger, ikke etter den første konflikten.
  • Hva skjer hvis kallet gjentas? Nettverk feiler midt i en forespørsel, og da må du prøve igjen. Kan du prøve igjen uten å opprette samme ordre to ganger?
  • Hvor mange kall får du gjøre? Nesten alle API-er har en grense. Finn den i dokumentasjonen før du finner den i produksjon.
  • Hvordan får du vite at noe har stoppet? Uten dette er svaret alltid «kunden ringer».
  • Hva er den manuelle utveien? Når noe først har gått skjevt, må noen kunne kjøre de siste to dagene på nytt uten å be om en ny utrulling.

Idempotens er det viktigste ordet i integrasjonsarbeid

Et kall er idempotent hvis det gir samme resultat om det utføres én gang eller fem ganger. Dette er ikke akademisk: uten det tør du ikke prøve igjen etter en timeout, og en integrasjon du ikke tør å prøve igjen i er en integrasjon som mister data.

I praksis betyr det at hvert kall bærer med seg en nøkkel du selv har laget — ordrenummeret, en UUID, en kombinasjon av kunde og dato — og at mottakersiden bruker den til å gjenkjenne «dette har jeg sett før». Gode API-er, som Stripe, tilbyr dette direkte med en egen header. Systemer som ikke gjør det må du bygge rundt: hold en logg over hva du har sendt, og sjekk den før du sender igjen.

Gjentakelse med backoff, og en kø for det som må vente

Når et kall feiler, er nesten alltid det riktige svaret å vente og prøve igjen — men ikke umiddelbart, og ikke i det uendelige. Vent litt lenger for hvert forsøk (ett sekund, to, fire, åtte), og legg en øvre grense. Uten backoff forvandler et kort avbrudd hos leverandøren seg til at du bombarderer et system som allerede har det vondt.

Det som feiler etter siste forsøk skal ikke forsvinne. Det skal havne et sted et menneske kan se: en tabell, en kø, en logg med noe mer enn «Error». Da er spørsmålet «hva gikk galt i går» et oppslag i stedet for en etterforskning.

Webhooks: du eier ikke rekkefølgen

Mange integrasjoner går motsatt vei: det andre systemet varsler deg når noe skjer. Det er raskere og billigere enn å spørre hvert femte minutt, men det kommer med to egenskaper folk oppdager for sent. Meldingene kan komme i annen rekkefølge enn hendelsene skjedde, og de kan komme flere ganger.

Behandle derfor hver melding som et faktum med et tidspunkt, ikke som en instruks. «Ordre 4711 hadde status betalt klokka 12.03» kan brukes selv om du får den etter «ordre 4711 hadde status sendt klokka 12.40». «Sett status til betalt» kan ikke. Og verifiser signaturen: en webhook-adresse er en åpen dør i systemet ditt.

Hva vi gjør annerledes i praksis

Vi bygger integrasjoner som en tydelig avgrenset del av systemet, med ett sted som snakker med det eksterne API-et og resten av koden bak et grensesnitt vi eier selv. Det gjør to ting: leverandøren kan byttes uten å rive i hele kodebasen, og integrasjonen kan testes uten å ringe noen andres server.

Deretter setter vi opp varsling før vi setter opp automatikk. En integrasjon som melder tydelig at den har stoppet er verdt mer enn en som nesten aldri stopper, men gjør det stille.

Når det ikke er verdt det

Noen ganger er svaret at integrasjonen ikke bør bygges. Skal ti rader flyttes én gang i måneden, er en eksport til regneark billigere å eie enn en synkronisering som må vedlikeholdes i årevis. Vi sier fra når det er tilfellet — det er raskere for alle enn å oppdage det etter at regningen er skrevet.

Vidd StudioProgramvarestudio i Fredrikstad
Aktuelt5 min lesetidHva er et design system, og trenger SMB-bedriften din et før dere skalerer produktet?Neste artikkel

Vil du heller at vi bygger det?

Si kort hva du vil lage, så svarer Jarand eller Daniel innen én virkedag. Første prat tar 30 minutter og koster ingenting.