Saltar al contenido

API migrada a Huma v2 con paridad del 100 %

Migré la API HTTP de Fiber a Huma v2 — 649 rutas y 760 operaciones — y alcancé y mantuve una correspondencia del 100 % entre las rutas que registra el servidor y la descripción OpenAPI que publica.

760 operaciones API migradas con una descripción fiel

Situación. La API comenzó en Fiber, con validación de solicitudes escrita a mano, endpoint por endpoint. Eso funciona bien cuando solo hay unos pocos endpoints. Deja de funcionar bien cuando crece la superficie: la validación artesanal se convierte en una carga de mantenimiento y aparecen pequeñas inconsistencias porque cada endpoint tiene sus propias comprobaciones particulares. Además, no existía en ningún lugar una descripción única de la estructura de la API.

Tarea. El objetivo era que la validación procediera de los tipos en lugar de comprobaciones escritas a mano, y disponer de un contrato real que describiera la API — sin detenerse para hacer una reescritura completa de golpe.

Acción. La capa HTTP pasó a Huma v2, situado sobre Fiber, por lo que se mantuvo el entorno de ejecución existente. Cada endpoint recibe estructuras de entrada y salida, y Huma genera a partir de esos tipos la validación de solicitudes y el modelado de respuestas. De ahí sale una descripción OpenAPI sin trabajo adicional, lo que significa que la documentación sigue al código en lugar de quedar obsoleta en una wiki. Todo lo nuevo se escribió sobre Huma y las rutas existentes se fueron migrando, dejando exactamente dos endpoints directamente en Fiber — los de WebSocket, donde realmente se necesita el socket y no encaja el modelo de solicitud/respuesta de Huma. El resultado ha crecido hasta 649 rutas que abarcan 760 operaciones, con una comprobación en CI que compara las rutas que registra realmente el servidor con las que anuncia la descripción OpenAPI. La paridad es del 100 %, y se mantiene porque una ruta sin describir hace fallar la compilación.

Resultado. Los nuevos endpoints obtienen validación y documentación actualizada sin que nadie tenga que hacer trabajo adicional, y toda una clase de errores en el tratamiento de solicitudes — los del tipo «se olvidó comprobar este campo aquí» — desapareció. Con 760 operaciones, la descripción es la única forma práctica de consultar la API, por lo que la garantía de que está completa importa más que cuando había cincuenta. El contrato tipado hizo que modificar la API fuera más seguro y entregársela a otra persona fuera más sencillo, porque los tipos indican qué espera un endpoint.

  • Bifurcación de vías ferroviarias
    Foto: music4life / Pixabay
  • Mapa plegable, mapa de carreteras, itinerario
    Foto: cocoparisienne / Pixabay

Aplique esta experiencia a su proyecto

Utilice «API migrada a Huma v2 con paridad del 100 %» como punto de partida para un reto similar en su organización. Los servicios que respaldan este trabajo están disponibles para su proyecto. Traspasos, procedimientos operativos y manuales para que su personal pueda operar el sistema sin llamar a quien lo construyó.

Explore nuestros servicios Póngase en contacto

Mire más allá del resultado

Lea la situación, las decisiones y el resultado de este ejemplo. Podemos hablar de qué partes se adaptan a sus restricciones y cuáles necesitan otro enfoque. API migrada a Huma v2 con paridad del 100 % — 760 operaciones API migradas con una descripción fiel

Explore nuestros servicios Póngase en contacto

Una parte de una trayectoria más amplia — y toda ella está en este sitio.

Cada entrada sigue la misma estructura: la situación, la tarea, lo que hicimos y lo que cambió.

Vea la trayectoria completa

Defina la mejora que necesita

Describa la decisión, las personas afectadas y las opciones ya consideradas. Podemos hacer explícitos los compromisos entre objetivos y dejar una recomendación documentada.

Vea cuánto cuesta Póngase en contacto

¿Quiere API con validación y buena documentación?

Pregunte por las decisiones detrás de «API migrada a Huma v2 con paridad del 100 %». Hablará con las personas que pueden explicar el trabajo y valorar su propio proyecto.

Explore nuestros servicios
welcome@engineer.company +45 50 10 61 84 Copenhague, Dinamarca
Código QR de Migré la API HTTP de Fiber a Huma v2 — 649 rutas y 760 operaciones — y alcancé y mantuve una correspondencia del 100 % entre las rutas que registra el servidor y la descripción OpenAPI que publica.
Llévese esta páginahttps://advisory.engineer.company/es/portfolio/migrated-the-api-to-huma-v2-at-100-parity/