Hvordan versionerer vi API'er uden at bryde eksisterende kunder?

For at versionere API'er uden at bryde eksisterende kunder er det vigtigt at vælge en passende versioneringsstrategi. En af de mest anvendte metoder er URI-versionering, hvor versionen inkluderes i URL'en, f.eks. '/v1/resource'. Alternativt kan header-versionering anvendes, hvor versionen angives i anmodningens header. Denne tilgang gør det muligt at holde API'ens URL uændret for eksisterende kunder, mens nye funktioner kan tilføjes i nye versioner.

Det er også essentielt at dokumentere eventuelle breaking changes og deprecations i release notes samt i OpenAPI/Swagger-specifikationer. Dette sikrer, at udviklere, der bruger API'en, er opmærksomme på ændringer og kan forberede sig på dem. At følge en 'design-first' tilgang, hvor OpenAPI fungerer som kilde til sandhed, kan hjælpe med at skabe klare kontrakter mellem API'et og dets brugere.

Introduktion af feature-flags kan give mulighed for at aktivere eller deaktivere nye funktioner uden at påvirke eksisterende funktionalitet. Dette kan være en effektiv metode til at teste nye funktioner med en begrænset brugergruppe, før de rulles ud til alle. Desuden kan backward-compatible udvidelser, hvor nye felter er optionale, være en god måde at tilføje funktionalitet uden at bryde eksisterende integrationer.

Endelig er det en god idé at have en klar plan for deprecations, herunder aftaler om, hvordan og hvornår eksisterende funktioner vil blive udfaset. At tilbyde klientbiblioteker eller transformationslag kan også lette migreringen for brugerne, hvilket gør overgangen til nye versioner mere glidende.

Kilder: Microsofts API guidelines ↗