Strategier til API-versionering

Det er en almindelig udfordring for udviklere at videreudvikle et API uden at ødelægge klientapplikationer.

Efterhånden som din applikation vokser, får du uundgåeligt brug for at tilføje nye funktioner, rette fejl eller forbedre eksisterende funktionalitet. Det kræver ofte ændringer i dit API's struktur.

Det store spørgsmål er: Hvordan indfører du disse ændringer uden at forstyrre eksisterende klientapplikationer, der er afhængige af dit API?

I modsætning til traditionelle REST-API'er, der ofte er afhængige af eksplicit versionsstyring (f.eks. /v1/users og /v2/users), tilskynder GraphQL til en anden filosofi: én enkelt API-version, der løbende udvikles.

Målet er at udvikle skemaet på en bagudkompatibel måde, så klienter kan tilpasse sig over tid uden tvungne opgraderinger.

En af de sikreste og mest almindelige måder at videreudvikle dit GraphQL-API på er at tilføje nye felter eller typer til dit eksisterende skema.

Da klienter udtrykkeligt anmoder om de data, de har brug for, påvirker tilføjelsen af nye felter ikke eksisterende klienter, der ikke forespørger efter disse nye tilføjelser. De ignorerer dem ganske enkelt.

Forestil dig en User-type. Hvis du har brug for at tilføje et email-felt, kan du blot udvide skemaet:

Når et felt ikke længere er nødvendigt eller bliver erstattet, bør du ikke fjerne det med det samme. Markér det i stedet som forældet.

Markeringen som forældet signalerer til klientapplikationer, at et felt er forældet og med tiden vil blive fjernet. Det giver klienterne tid til at opdatere deres kode og skifte til nyere alternativer.

GraphQL indeholder det indbyggede @deprecated-direktiv, som kan markere felter eller enum-værdier som forældede. Du kan også angive en reason for at forklare, hvorfor det er forældet, og foreslå et alternativ.

I Spring Boot GraphQL kan du anvende annotationen @Deprecated fra Java direkte på felter i dine dataklasser eller på dine resolver-metoder. GraphQL-biblioteket afspejler derefter dette i dit skema.

Omdøbning af et eksisterende felt betragtes som en inkompatibel ændring, fordi klienter straks mister adgangen til feltet under det gamle navn.

Den anbefalede strategi består af to trin:

• Trin 1: Tilføj det nye felt med det ønskede navn.
• Trin 2: Markér det gamle felt som forældet, og anbefal klienterne at skifte til det nye.

Når brugen af det gamle felt er faldet til nul, kan du fjerne det uden risiko.

Fjernelse af et felt fra dit GraphQL-skema er en alvorlig inkompatibel ændring. Enhver klient, der stadig forespørger efter feltet, vil modtage en fejl.

Det bør kun gøres efter en længere periode med markering som forældet, tydelig kommunikation med dine klienter og bekræftelse af, at ingen aktive klienter længere bruger feltet.

Ændringer af inputtyper (som bruges til mutationer) kræver også omhyggelige overvejelser:

• Tilføjelse af nye valgfrie felter: Som regel sikkert.
• Tilføjelse af nye påkrævede felter: En inkompatibel ændring. Overvej at oprette en ny inputtype eller gøre feltet valgfrit med en standardværdi.
• Ændring af et felts type: En inkompatibel ændring.

Ligesom med felter kan du markere inputfelter som forældede.

GraphQL's styrke ligger i muligheden for en gradvis udvikling uden traditionel versionsstyring. Ved at følge bedste praksis kan du minimere forstyrrelser for klienterne:

• Foretræk tilføjelser: Tilføj om muligt altid nye felter eller typer i stedet for at ændre eksisterende.
• Markér som forældet, slet ikke: Brug @deprecated-direktivet til at signalere, at felter med tiden bliver fjernet, så klienterne kan skifte til alternativer.
• Kommunikér: Informér dine klienter om kommende ændringer og tidsplaner for forældelse.
• Overvåg brugen: Følg klienternes brug af forældede felter, før du fjerner dem.

Denne tilgang fremmer et stabilt API, der løbende kan udvikles.