Hoppa till innehållet

Migrerade API:t till Huma v2 med 100 % paritet

Migrerade HTTP‑API:t från Fiber till Huma v2 — 649 sökvägar och 760 operationer — och nådde och behöll 100 % paritet mellan de rutter som servern registrerar och den OpenAPI‑beskrivning den publicerar.

760 flyttade API‑operationer, med beskrivningen fortsatt korrekt

Situation. API:et började sitt liv på Fiber, med validering av anrop som skrevs för hand, slutpunkt för slutpunkt. Det fungerar när det finns en handfull slutpunkter. Det slutar fungera när ytan växer: den handskrivna valideringen blir en ständig underhållsbörda, och små inkonsekvenser smyger sig in eftersom varje slutpunkts kontroller är ett eget litet specialfall. Och det fanns ingenstans en samlad beskrivning av hur API:et såg ut.

Uppgift. Målet var validering som följde av typerna i stället för av handskrivna kontroller, och ett verkligt kontrakt som beskrev API:et — utan att stanna upp för en omskrivning av allt i ett enda svep.

Handling. HTTP‑lagret flyttades till Huma v2, som ligger ovanpå Fiber, så den befintliga körmiljön fick vara kvar. Varje slutpunkt får structar för indata och utdata, och Huma genererar valideringen av anropen och modelleringen av svaren utifrån de typerna. En OpenAPI‑beskrivning kommer på köpet, vilket betyder att dokumentationen håller jämna steg med koden i stället för att ruttna i en wiki. Allt nytt skrevs mot Huma och de befintliga rutterna migrerades över, med exakt två slutpunkter kvar på ren Fiber — de för WebSocket, där du verkligen vill åt själva socketen och Humas modell med anrop och svar inte passar. Det har vuxit till 649 sökvägar med 760 operationer, och en kontroll i CI som jämför de rutter som servern faktiskt registrerar med dem som OpenAPI‑beskrivningen utlovar. Överensstämmelsen är 100 %, och den ligger kvar där eftersom en rutt som saknar beskrivning stoppar bygget.

Resultat. Nya slutpunkter får validering och aktuell dokumentation utan att någon behöver lägga extra arbete på det, och en hel klass av buggar i anropshanteringen — av typen ”oj, vi glömde kontrollera det fältet här” — försvann. Med 760 operationer är beskrivningen det enda praktiska sättet för någon att läsa API:et, så garantin att den är komplett väger tyngre än den gjorde vid femtio. Det typade kontraktet gjorde API:et både säkrare att ändra och lättare att lämna över till någon annan, eftersom typerna talar om vad en slutpunkt förväntar sig.

  • Järnväg, järnvägsspår, knutpunkt
    Foto: music4life / Pixabay
  • Vikbar karta, vägkarta, resplan
    Foto: cocoparisienne / Pixabay

Använd erfarenheten i ert projekt

Använd ”Migrerade API:t till Huma v2 med 100 % paritet” som utgångspunkt för en liknande utmaning i er organisation. Tjänsterna bakom arbetet finns tillgängliga för ert projekt. Överlämningar, driftinstruktioner och manualer som låter din egen personal driva systemet utan att ringa den som byggde det.

Se våra tjänster Hör av er

Se bakom resultatet

Läs om situationen, besluten och resultatet i exemplet. Vi kan diskutera vad som passar era förutsättningar och vad som kräver ett annat angreppssätt. Migrerade API:t till Huma v2 med 100 % paritet — 760 flyttade API‑operationer, med beskrivningen fortsatt korrekt

Se våra tjänster Hör av er

En del av en längre historik — och den finns i sin helhet här.

Varje post är skriven på samma sätt: situationen, uppgiften, vad vi gjorde och vad som förändrades.

Se hela historiken

Definiera förbättringen ni behöver

Ta med beslutet, människorna som berörs och alternativen som övervägts. Vi kan tydliggöra avvägningarna och lämna en dokumenterad rekommendation.

Se vad det kostar Hör av er

Vill du ha validerade, väldokumenterade API:er?

Fråga om besluten bakom ”Migrerade API:t till Huma v2 med 100 % paritet”. Ni talar med personer som kan förklara arbetet och bedöma ert eget projekt.

Se våra tjänster
welcome@engineer.company +45 50 10 61 84 Köpenhamn, Danmark
QR-kod för Migrerade HTTP‑API:t från Fiber till Huma v2 — 649 sökvägar och 760 operationer — och nådde och behöll 100 % paritet mellan de rutter som servern registrerar och den OpenAPI‑beskrivning den publicerar.
Ta med dig den här sidanhttps://advisory.engineer.company/sv/portfolio/migrated-the-api-to-huma-v2-at-100-parity/