Har migreret API'et til Huma v2 med 100 % paritet

Situation. API’et begyndte sit liv på Fiber med request‑validering skrevet i hånden, endpoint for endpoint. Det går fint, så længe der er en håndfuld endpoints. Det holder op med at gå, efterhånden som API’et vokser: den håndskrevne validering bliver en løbende vedligeholdelsesbyrde, og små inkonsistenser sniger sig ind, fordi hvert endpoints tjek er sit eget lille særtilfælde. Og der fandtes ingen samlet beskrivelse af API’ets struktur.

Opgave. Målet var validering, der kom fra typerne i stedet for fra håndskrevne tjek, og en egentlig kontrakt, der beskrev API’et — uden at sætte alt andet på pause for en big bang‑omskrivning.

Handling. HTTP‑laget blev flyttet over på Huma v2, der ligger oven på Fiber, så den eksisterende runtime blev bevaret. Hvert endpoint får input- og output‑structs, og Huma genererer request‑valideringen og responsmodelleringen ud fra de typer. En OpenAPI‑beskrivelse følger med gratis, hvilket betyder, at dokumentationen følger koden i stedet for at rådne i en wiki. Alt nyt blev skrevet mod Huma, og de eksisterende ruter blev migreret over, så præcis to endpoints er tilbage på rå Fiber — WebSocket‑endpointene, hvor man reelt har brug for selve socketten, og hvor Humas request/response‑model ikke passer. I dag er det vokset til 649 paths med 760 operationer og et tjek i CI, som sammenligner de ruter, serveren faktisk registrerer, med dem, OpenAPI‑beskrivelsen oplyser. Pariteten er 100 %, og den bliver der, fordi en rute, der ikke er beskrevet, får buildet til at fejle.

Resultat. Nye endpoints får validering og opdateret dokumentation, uden at nogen skal gøre en ekstra indsats for det, og en hel kategori af fejl i request‑håndteringen — “nå ja, vi glemte at tjekke det felt her”-slagsen — forsvandt. Med 760 operationer er beskrivelsen den eneste praktiske måde at læse API’et på, så garantien for, at den er komplet, betyder mere, end den gjorde ved halvtreds. Den typede kontrakt gjorde API’et både sikrere at ændre og lettere at overdrage til andre, for typerne viser, hvad et endpoint forventer.