API-design: Sådan bygger I integrationer, der holder

Et API starter ofte beskedent: et system skal hente kunder, sende en ordre eller opdatere en status. Et par år senere bruger ERP, webshop, app, BI, partnere og interne værktøjer det samme API. Så bliver de tidlige designvalg pludselig dyre.

Derfor betragter vi et API som en langsigtet kontrakt mellem systemer. Et godt API handler ikke kun om endpoints og JSON. Det handler om at gøre ændringer mulige uden at skabe unødvendig risiko i alle de systemer, der er koblet på.

Start med forretningens begreber – ikke databasen

Et godt API beskriver domænet: kunder, ordrer, produkter, projekter, sager og betalinger. Hvis API'et i stedet afspejler interne tabeller én til én, bliver databaseimplementationen hurtigt en ekstern kontrakt. Så kan en ellers simpel ændring i datamodellen få konsekvenser for mange integrationer.

Tænk derfor først over, hvad en forbruger faktisk skal kunne gøre. Det giver et mere forståeligt API og frihed til at ændre systemet bagved.

Konsistens er en feature

Udviklere lærer hurtigt et API's mønstre. Hvis pagination, filtrering, datoformater, fejl, statuskoder og navngivning fungerer ens overalt, falder integrationsarbejdet markant. Den bedste oplevelse er, når næste endpoint opfører sig omtrent, som udvikleren forventer.

Lav derfor fælles konventioner tidligt. Det er langt billigere end at rette 40 endpoints senere.

Design til ændringer fra starten

API'er lever ofte længere end den applikation, de først blev bygget til. Nye felter er typisk nemme at tilføje bagudkompatibelt, mens ændrede betydninger, slettede felter og nye obligatoriske input kan bryde eksisterende klienter.

Versionering kan være nødvendigt, men bør ikke være standardløsningen på alle ændringer. Før et breaking change bør I vide, hvem der bruger den eksisterende kontrakt, og have en konkret migrationsperiode.

Fejlbeskeder skal kunne bruges af både mennesker og software

En 400-fejl fortæller kun, at noget er galt. Et integrationsvenligt API returnerer også en stabil fejlkode og en forståelig beskrivelse af problemet. Det gør det muligt for klienten at reagere korrekt og for udvikleren at fejlfinde uden først at ringe til leverandøren.

Sikkerhed handler også om autorisation

Autentifikation fortæller, hvem klienten er. Autorisation afgør, hvad den må. De to ting blandes ofte sammen. Overvej adgang pr. kunde, organisation, ressource og handling – og returnér aldrig flere data, end integrationen faktisk har behov for.

Rate limiting, inputvalidering, audit logs og håndtering af secrets bør være en del af designet og ikke noget, der monteres bagefter.

Dokumentation skal kunne stole på

En OpenAPI-specifikation kan både drive dokumentation, klientgenerering og automatiske tests. Men værdien forsvinder, hvis specifikationen ikke følger den kode, der er i produktion. Derfor bør API-kontrakten være en del af udviklings- og deploymentprocessen.

Gode eksempler betyder også meget. Vis et realistisk request, et normalt response og de mest almindelige fejlscenarier. Det sparer ofte mere integrationstid end lange tekstbeskrivelser.

Observability: Hvad sker der, når integrationen fejler kl. 02?

Et API er først rigtig driftbart, når teamet kan se, hvad der foregår. Log korrelations-id'er, svartider og fejl uden at lække følsomme data. Mål fejlrate og performance, og sørg for at en konkret transaktion kan følges gennem flere systemer.

Når vi overtager et eksisterende API

Vi starter normalt med at kortlægge forbrugere, kontrakter, sikkerhed, performance, deployment og de ændringer, der oftest skaber problemer. Derefter kan forbedringer laves gradvist bag den eksisterende kontrakt.

Det er sjældent nødvendigt at smide API'et væk og begynde forfra. Ofte kan de største problemer løses ved at skabe konsistens, forbedre dokumentationen og isolere gammel implementation bag en stabil grænse.

Et godt API reducerer prisen på den næste integration

API-design er derfor ikke kun en teknisk disciplin. Det afgør, hvor hurtigt virksomheden senere kan koble nye systemer, partnere og digitale produkter på. Den ekstra omtanke i starten betaler sig, når integration nummer to, fem og ti skal bygges.

Uptime udvikler og overtager integrationsplatforme og API'er mellem blandt andet ERP, CRM, web, apps og specialbyggede forretningssystemer.

Et godt API er en stabil kontrakt mellem systemer. Design efter de næste års ændringer – ikke kun efter den integration, der skal virke i dag.