Migrerte API‑et til Huma v2 med 100 % paritet
Migrerte HTTP‑API‑et fra Fiber til Huma v2 — 649 stier og 760
operasjoner — og nådde og holdt 100 % samsvar mellom rutene serveren
registrerer og OpenAPI‑beskrivelsen den publiserer.
2025

Situasjon. API‑et ble opprinnelig bygget på Fiber, med
forespørselsvalidering skrevet for hånd, endepunkt for endepunkt.
Det går fint så lenge det finnes en håndfull endepunkter. Det
slutter å gå fint etter hvert som API‑flaten vokser: den håndskrevne
valideringen blir en vedvarende vedlikeholdsbyrde, og små
inkonsekvenser sniker seg inn fordi kontrollene i hvert endepunkt er
et lite unikum. Og en samlet beskrivelse av hvordan API‑et så ut,
fantes ikke noe sted.

Oppgave. Målet var at valideringen skulle komme fra typene i stedet
for fra håndskrevne kontroller, og en faktisk kontrakt som beskrev
API‑et — uten å stoppe opp for å skrive alt om på én gang.

Handling. HTTP‑laget ble flyttet over på Huma v2, som ligger oppå
Fiber, slik at det eksisterende kjøremiljøet ble beholdt. Hvert
endepunkt får egne struct‑typer for inndata og utdata, og Huma
genererer forespørselsvalideringen og responsmodelleringen fra disse
typene. En OpenAPI‑beskrivelse følger med på kjøpet, slik at
dokumentasjonen følger koden i stedet for å forfalle i en wiki. Alt
nytt ble skrevet mot Huma, og de eksisterende rutene ble migrert
over, med nøyaktig to endepunkter igjen på ren Fiber —
WebSocket‑endepunktene, der man faktisk vil ha selve socketen og
forespørsel/svar‑modellen til Huma ikke passer. Det har vokst til
649 stier med 760 operasjoner, og en kontroll i CI som sammenligner
rutene serveren faktisk registrerer, med dem OpenAPI‑beskrivelsen
oppgir. Pariteten er 100 %, og den holder seg der fordi en rute som
ikke er beskrevet, får bygget til å feile.

Resultat. Nye endepunkter får validering og oppdatert dokumentasjon
uten at noen må gjøre ekstra arbeid for det, og en hel klasse feil i
forespørselshåndteringen — typen «å, vi glemte å sjekke det feltet
her» — forsvant. Med 760 operasjoner er beskrivelsen den eneste
praktiske måten noen leser API‑et på, så garantien for at den er
fullstendig, betyr mer enn den gjorde ved femti. Den typede
kontrakten gjorde API‑et både tryggere å endre og enklere å
overlevere til andre, fordi typene viser hva et endepunkt forventer.

Kategorier:
1Plattformarkitektur	/nb/categories/platform-architecture/	software.engineer.company	70
1Backend‑utvikling	/nb/categories/backend/	software.engineer.company	70
1API‑er og integrasjon	/nb/categories/api/	software.engineer.company	70
1Migrering og modernisering	/nb/categories/migration/	software.engineer.company	70
1Testing og kvalitetssikring	/nb/categories/testing/	software.engineer.company	70
1Dokumentasjon	/nb/categories/documentation/	software.engineer.company	70

Tjenester:
1Plattform- og løsningsarkitektur	/nb/services/platform-architecture/	software.engineer.company	70
1Backend- og API‑utvikling	/nb/services/backend-development/	software.engineer.company	70
1Verktøy for AI‑agenter og MCP‑servere	/nb/services/ai-tools/	software.engineer.company	70
1Teknisk dokumentasjon	/nb/services/technical-documentation/	software.engineer.company	70

hDenne siden på nettet	URL:https://software.engineer.company/nb/portfolio/migrated-the-api-to-huma-v2-at-100-parity/	software.engineer.company	70
