Sin embargo, el autor encontró algunos problemas graves después de que se lanzó el proyecto :
1. Falta de documentación y especificaciones API completas :
· La documentación de la API está incompleta y llena de errores y no se puede utilizar como referencia precisa.
· No existe un proceso de prueba de API acordado, lo que permite que el equipo de desarrollo de backend cambie y publique la API a voluntad sin previo aviso. Estos cambios suelen ser errores y rompen la integración con los clientes API.
2. Marco y validación de API inadecuados :
El equipo de backend utilizó un marco de Flask inadecuado e implementó una validación de carga útil compleja por su cuenta, la mayor parte de la cual no fue probada.
· La parte de verificación tiene una gran cantidad de código, incluida la fecha, la marca de tiempo y la verificación del formato de cadena, pero no se ha probado completamente, lo que ralentiza seriamente el progreso del proyecto.
Por lo tanto , para resolver los problemas anteriores , es necesario reparar y mejorar la documentación de la API para garantizar su precisión e integridad ; establecer un marco de API apropiado para mejorar la calidad y la capacidad de prueba del código y establecer especificaciones de API estrictas para evitar el lanzamiento de versiones que no lo hagan; no cumple con las especificaciones.
Arreglar el diseño y la documentación de API
De los problemas expuestos anteriormente se puede ver que el equipo de desarrollo no comprende las mejores prácticas de REST API y la especificación OpenAPI. Por lo tanto, el equipo de desarrollo primero debe comprender OpenAPI y cómo funciona, e integrar la documentación de la API en la especificación de OpenAPI para tener una comprensión más clara del comportamiento esperado de la API.
En el proceso de integración de la documentación en la especificación OpenAPI, descubrimos muchos problemas con diseños de API anteriores. Por ejemplo, los formatos de fecha personalizados anteriormente requerían una lógica de validación personalizada en el servidor y la interfaz de usuario. Resolvimos este problema cambiando al estándar ISO compatible con OpenAPI para representar fechas.
Además, algunos modos son tan flexibles que la validación es casi ineficaz. Para mejorar la validación, refactorizamos los esquemas y creamos un modelo con diferentes puntos finales para cada entidad, haciéndolo más utilizable.
Los métodos HTTP y los códigos de estado se utilizaron de manera inapropiada en el diseño anterior. El equipo solo utiliza métodos GET y POST y todas las respuestas devuelven un código de estado 200. Este uso inadecuado hace que no quede claro al intentar crear, eliminar o actualizar recursos. Para resolver este problema, hemos redefinido el uso de métodos HTTP y devolvemos correctamente el código de estado apropiado para indicar con mayor precisión el éxito o el fracaso de la solicitud.
Otra limitación del diseño anterior era la "reutilización de puntos finales". Aunque parece guardar código, en realidad expone demasiados detalles de implementación. Por lo tanto, debemos enfatizar el concepto de diseñar la API primero y luego considerar la implementación.
La fusión de la especificación API con OpenAPI fue un punto de inflexión importante para el proyecto. A partir de entonces, pudimos ejecutar un servidor simulado para construir y probar la interfaz de usuario antes de integrarla con el backend, así como verificar la implementación del backend según las especificaciones. Usamos Prism para ejecutar el servidor simulado y Dredd para verificar la implementación del servidor (aunque ahora prefiero usar Schemathesis). Esto permite que los proyectos se desarrollen de forma más clara y eficiente .
Arreglar el proceso de lanzamiento de API
Incluso si hay un documento API, si no se prueba con la especificación API antes de su lanzamiento, la función del documento será limitada. Si bien la documentación en sí nos ayuda a comprender cómo funciona la API, su verdadero poder reside en su función como herramienta de verificación: verificar que el servidor esté implementado correctamente.
Para garantizar que el servidor API funcione como se esperaba, incorporé el conjunto de pruebas Dredd en el servidor de integración continua. Nadie puede fusionar y publicar código nuevo a menos que pase la validación de Dredd y cumpla con la especificación de la API. Este paso permite al equipo evitar modificaciones inadvertidas en el servidor API. De ahora en adelante, todos los cambios en el servidor deben documentarse con anticipación y se debe garantizar que el servidor API siga estos cambios antes de fusionarlos o publicarlos. Este enfoque garantiza la estabilidad y coherencia del servidor.
Elija el marco de desarrollo de API adecuado
Anteriormente, el equipo implementó el servidor API utilizando el marco Flask, un marco Python popular para crear aplicaciones web. Construyeron la API con Flask básico y escribieron una gran cantidad de código personalizado para validar la carga útil de la API. Este es un error común que cometen muchos desarrolladores de API sin experiencia.
Crear una capa de validación de API personalizada no es indeseable, pero confiar excesivamente en este enfoque puede llevar a reinventar la rueda. La API requiere una lógica de validación compleja para manejar la carga útil y la URL (ruta y parámetros de consulta), que deben implementarse en toda la API. Por lo tanto, si insiste en crear su propia capa de verificación API, eventualmente producirá un marco API. Sin embargo, hay muchos marcos de desarrollo de API excelentes disponibles, así que ¿por qué no elegir uno de ellos?
Específicamente para Flask, hay varias opciones a considerar. Pero no todos los marcos son iguales. Por ejemplo, flasgger, restx (sucesor de flask-restplus), flask-RESTful y flask-smorest, etc. Con tantas opciones, ¿cómo se toma una decisión?
Al elegir un marco de desarrollo de API REST, se deben considerar los siguientes factores:
· Compatibilidad con OpenAPI : el marco debería permitir la creación sencilla de API REST y generar automáticamente documentación de API, garantizando la exactitud de la verificación de la carga útil. Los marcos de referencia incluyen Flasgger y flask-smorest.
· Validación de datos sólida : la validación de cargas útiles requiere una biblioteca de validación de datos sólida para manejar varios atributos y tipos. La biblioteca debe admitir propiedades opcionales y obligatorias, como formatos de cadena (fecha ISO y UUID), así como una validación de tipos estricta y relajada. En el ecosistema Python, pydantic y marshmallow son excelentes bibliotecas de validación de datos, y Flasgger y flask-smorest pueden usar marshmallow.
Validación integral : el marco debe admitir la validación de cargas útiles de solicitud, cargas útiles de respuesta, parámetros de ruta URL y parámetros de consulta URL. Es posible que algunas bibliotecas solo validen la carga útil de la solicitud e ignoren los parámetros de URL o la carga útil de la respuesta. Asegúrese de que el marco proporcione al menos una forma de hacer cumplir las reglas de validación. Si usa marshmallow, la carga útil de respuesta se puede verificar directamente usando su modelo.
· Madurez : elija una biblioteca que sea madura, estable y que tenga apoyo comunitario activo. Debe tener buena documentación y la capacidad de resolver rápidamente los problemas de los usuarios.
Después de evaluar los factores anteriores, seleccionamos flask-smorest, un complemento de Flask que admite el uso de marshmallow para crear fácilmente la verificación de datos para las API REST. Puede simplificar el proceso de verificación de datos y reducir la cantidad de código personalizado. Tanto las cargas útiles de solicitud como de respuesta ahora están validadas correctamente y marshmallow también maneja la validación de consultas URL y parámetros de ruta.
Elegir el marco API adecuado nos permite tener una API funcional. Debido a que el marco maneja los detalles de la capa API, podemos centrarnos más en la lógica empresarial y el modelo de datos de la aplicación, lo que da como resultado una mayor velocidad de desarrollo y la capacidad de lanzar mejor software con más frecuencia.
Considere todo para crear una excelente API
En la Internet actual, las API están en todas partes y son inevitables. Sin embargo, crear realmente una buena API es una tarea compleja. Al igual que escribir código que sea legible y fácil de mantener, crear una interfaz de alta calidad, fácil de usar y de modificar también es un desafío en el desarrollo de API.
Proporcionar una API de alta calidad es difícil porque debe ser coherente con los requisitos comerciales, es decir, el cliente y el servidor deben utilizar las mismas convenciones y especificaciones; de lo contrario, será difícil lograr la integración.
Lograr este objetivo requiere considerar múltiples aspectos: recopilar los requisitos del cliente, traducir los requisitos en detalles técnicos, diseñar la API, escribir documentación, elegir un marco API apropiado y usarlo correctamente, probar la API y garantizar que la implementación cumpla con las especificaciones de diseño. Esto no incluye aspectos como la seguridad, implementación y operación de API.
Cuando se trata de crear API críticas para el negocio, el consejo es no dejarlo solo en manos de desarrolladores junior. Pueden participar, pero se necesita un desarrollador senior que guíe su trabajo. Si no tiene experiencia en desarrollo de API, siga el camino de las mejores prácticas: primero diseñe la API, luego escriba la documentación, impleméntela de acuerdo con la especificación y verifíquela. ¡No reinventes la rueda, elige el marco adecuado!
Aunque puede llevar algún tiempo aprender OpenAPI, comprender el marco de prueba de API, investigar el marco de desarrollo de API, etc., vale la pena. De lo contrario, quedará atrapado en un círculo vicioso de integración de API y problemas de calidad del software que obstaculizarán el progreso del proyecto e incurrirán en enormes costos para solucionar los problemas.
Si tiene recursos suficientes y desarrolladores de API experimentados, la probabilidad de crear la API correctamente aumentará considerablemente y podrá ahorrar mucho dinero. Además, también debemos prestar atención a la gestión de API. Muchos problemas radican no solo en los costos de desarrollo y gastos iniciales, sino también en problemas de código oculto durante el proceso de desarrollo y entregas poco claras de los empleados responsables, que pueden causar peligros ocultos. Por lo tanto, Power Simple Integration cree que la administración de API puede utilizar herramientas de terceros para administrar las API de una sola vez, involucrar múltiples roles, evitar eludir responsabilidades y mejorar la eficiencia del desarrollo.
Enlace original : Tiempo de comercialización más rápido con API-first | por José Haro Peralta Medio --- prioridad de API para acelerar el tiempo de comercialización |