Et API er en kontrakt. Ikke bare et endpoint

Det er let at lave et API, der virker i dag. Det svære er at lave et API, som stadig er behageligt at arbejde med, når fem andre systemer er blevet afhængige af det.

Vi ser ofte API'er, der i praksis er blevet en direkte fjernbetjening til databasen. Det kan gå hurtigt i begyndelsen, men interne tabeller, feltnavne og særheder bliver pludselig til en offentlig kontrakt, som er dyr at ændre senere.

Start med forretningens begreber

Et API bør tale samme sprog som forretningen. Kunder, ordrer, produkter, sager og betalinger er bedre kontrakter end tilfældige databasetabeller. Det gør integrationen lettere at forstå og giver backend-teamet frihed til at ændre implementationen bagved.

Konsistens slår kreativitet

Navngivning, fejlformater, pagination, datoer og statuskoder bør fungere ens. Den bedste feedback et API kan få er næsten kedelig: at udvikleren kunne gætte, hvordan næste endpoint virkede, uden at læse hele dokumentationen.

Versionering er ikke en undskyldning for at bryde ting

Nye API-versioner er nogle gange nødvendige, men bagudkompatible ændringer er næsten altid billigere. Hvis et breaking change er uundgåeligt, bør man vide præcis hvilke klienter der stadig bruger den gamle kontrakt, og hvor længe de får til at migrere.

Sikkerhed er mere end login

Autentifikation løser kun spørgsmålet om, hvem brugeren er. Et godt API skal også tage stilling til, hvad brugeren må se og ændre, hvor meget data der må returneres, hvordan input valideres, og hvordan misbrug opdages.

Dokumentationen er en del af produktet

OpenAPI-specifikationer og gode eksempler sparer timer hos alle, der skal integrere. Endnu vigtigere: dokumentationen skal følge koden. En flot guide, der beskriver noget andet end det faktiske API, er værre end ingen guide.

Når vi overtager et eksisterende API

Vi kortlægger først forbrugere, sikkerhed, kontrakter, performance og ændringshistorik. Derefter kan API'et typisk forbedres trinvis. Man behøver sjældent bryde alle integrationer for at få en bedre arkitektur.