API first: Lo primero es lo primero.

¿Qué es API first?

El enfoque API first se centra en planificar la API mediante un contrato de diseño usando RAML o Open API. Este contrato asegura coherencia, reutilización e interoperabilidad en la API. Permite usar herramientas gratuitas para crear documentación y pruebas basadas en las especificaciones del contrato.

El problema de no usar API first: no planificar las APIs

Si tu proyecto web ha requerido una API como alternativa de comunicación entre aplicaciones o simplemente has trabajado en el desarrollo de este tipo de servicios es muy probable que hayas ido por el camino tradicional de muchas empresas de software, comenzando por escribir directamente documentos y documentos de código, con poca o quizás ninguna planificación previa.

Resultado final: tu API estará lista en un corto período de tiempo si no sufres muchos contratiempos y todas las partes que la requieran podrán utilizarla si, y solo si, entienden cómo hacerlo.

Me dirás: “No hay problema, todos los documentos de código tienen anotaciones, comentarios e incluso estoy trabajando en una descripción manual para su uso desde cero, por lo que las partes que necesitan utilizar mi API encontrarán como hacerlo fácilmente.“

Bueno, y ¿qué pasa con las pruebas de validación? Seguramente se llevarán a cabo una vez finalizada la implementación de la API y a partir de sus resultados comenzará un bucle de correcciones, reelaboración y actualización de anotaciones que en muchos casos hubiesen sido innecesarias con un poco de planificación previa y la ejecución de pruebas, con la participación activa de todas las partes involucradas.

Esto sin mencionar los obstáculos o retrasos que pueden surgir a futuro si el proyecto escala.

Este enfoque de trabajo directo a la implementación, o “code-first” como se le conoce, se encuentra cada vez más en extinción cuando las API tiene muchos endpoints o es para el consumo interno del grupo de trabajo. ¿Entonces, cuál es el camino?

¿Qué es API first y API-design first?

Enfoques más actuales emergen hoy en busca de la planificación y especificación de contratos de diseño para las API que satisfagan la lógica del negocio de manera sostenible y escalable. Recuerda que la API no es más que el lenguaje común que utilizarán para comunicarse todas las partes de un proyecto y por tanto, debe ser consensuado, especificado, validado y de dominio colectivo.

Seguro que te suenan términos como API first o API-design first. Pero ¿qué son en esencia estos términos? ¿No son lo mismo? Pues no.

El enfoque API first prioriza la planificación de la API a través de la especificación del contrato de diseño, utilizando lenguajes escritos que seguramente has oído mencionar como RAML o OpenAPI. Iniciar el trabajo con un contrato de API garantiza la coherencia, la reutilización y la amplia interoperabilidad de la API resultante, siendo posible utilizar herramientas gratis para generar documentación y ejemplos de prueba a partir de las especificaciones establecidas en el contrato de la API.

Por otra parte, API-design first resulta un enfoque un poco más ambicioso en cuanto a planificación. Antes de comenzar a escribir cualquier línea de código o incluso de especificación del contrato, las partes involucradas técnicas y no técnicas podrán discutir las funcionalidades de la API, la estructura del contrato, realizar simulacros de funcionamiento y trazar las posibles pruebas de validación. Todo ello en un ciclo corto de retroalimentación. Luego, podrán ser definidas en código las especificaciones de la API y partir de ahí, desarrolladores de las aplicaciones frontend, backend, calidad…podrán implementar el desarrollo en paralelo con apoyo adicional de documentación y entornos de prueba.

Dado que ambos enfoques enfatizan la importancia de los documentos y contratos de diseño, desde Redsauce te recomendamos combinar ambos. Al fin y al cabo, cuando has implementado cualquiera de ellos entonces indirectamente has realizado la mitad del trabajo necesario para implementar el otro; la diferencia recae en el orden que estableces para abordar el trabajo. Si lo piensas un minuto, los enfoques API-design first y API first comparten un mismo grupo de etapas de trabajo, y su diferencia radica en la secuencia con que abordan o ejecutan cada etapa para desarrollar un servicio de API.

Combinar los enfoques API first y API-design first

Entonces, ¿cómo lo hacemos?

Comienza planificando y especificando tu API, en un proceso que fluya en paralelo con la discusión y valoración de las partes sobre las especificaciones ya establecidas. Haz las correcciones y una vez que esté bien definido el contrato, inicia con el proceso de desarrollo de la documentación, entornos de prueba y pruebas de validación.

Con herramientas como Open API y Postman abordar estos enfoques durante el desarrollo de APIs es más simple que nunca. Pero ese es un tema que abordaremos próximamente.

Recuerda que si tu, o tu equipo necesitáis ayuda con vuestras pruebas de API, en Redsauce somos especialistas en api testing e integrar las APIs en los pipelines de desarrollo. Puedes ver este y otros consejos en nuestro ebook, o viniendo a visitarnos