Definición de API con YAML y OpenAPI

Actualmente, casi cualquier desarrollo requiere que el trabajo se lleve a cabo por varios equipos, de la forma más independiente posible. Entre otras situaciones, cuando trabajamos con API es necesario ponernos de acuerdo con otros equipos, para que sus consultas a nuestro API cumplan una serie de especificaciones. Si hacemos cualquier cambio en el API, los equipos que lo utilicen podrían tener problemas, que no siempre serán inmediatos, que podrían retrasar el desarrollo considerablemente.

Para evitar estos problemas, podemos establecer contratos, de forma que, como una de las primeras fases del desarrollo, proporcionaremos a los otros equipos todas las especificaciones necesarias para utilizar nuestros API. De esta forma, facilitamos enormemente la integración.

Se suele decir que “muchas horas de codificación nos permitirán ahorrarnos una hora de planificación”. Esta afirmación exagerada, aunque resulte chocante, describe muchas veces una forma de trabajo que, no por ser habitual, es correcta. Esto adquiere especial importancia con los API. Tenemos la costumbre de ponernos a codificar de inmediato, cuando sentarnos a pensar un momento, y a organizar nuestros API, nos va a ahorrar muchísimo tiempo de desarrollo.

Retomando el tema, anteriormente comentado en otro post, de las herramientas que nos ayudan con nuestros API, volveremos a ver cómo Swagger nos ayuda a trabajar con estos temas. Hoy veremos algo más sobre OpenAPI (antes llamado Swagger), convertido ya en estándar.

Para definir un contrato de API, vamos a utilizar YAML, un sencillo lenguaje de serialización, fácilmente comprensible por humanos, y que se puede utilizar con las herramientas de Swagger para incluso generar código. Como anotación al margen, existen pocos escenarios en los que las herramientas de generación de código son realmente útiles, pero el trabajo con API es uno de estos escenarios en los que resulta de mucha utilidad. Estas herramientas escribirán por nosotros el código de un esqueleto de API, dejándonos tan sólo la tarea de la lógica. Otra buena forma de ahorrarnos tiempo.

Es posible utilizar cualquier editor de textos para esta tarea, pero lo más cómodo (sobre todo sin conocer el lenguaje), es utilizar un buen editor, como el que nos ofrece Swagger.

Vamos a probar a definir un API básico con esta herramienta, disponible en su web http://editor.swagger.io

En la parte izquierda de la pantalla tenemos el editor, y en la derecha una previsualización de la documentación de Swagger para el API que estamos editando.

La definición de un API en YAML contiene lo siguiente:

• Información general sobre el API
• Rutas disponibles
• Operaciones posibles en cada ruta

Algo muy importante utilizando el editor, es que la identación es muy importante, por lo que si aparecen errores de sintaxis que no tienen explicación aparente, es muy normal que debamos corregir que cada cosa esté en el nivel que le corresponde. Como truco rápido, podemos usar la opción del menú Edit → Convert to YAML, que intentará interpretar de nuevo nuestro documento.

Como ejemplo, definimos en el editor las propiedades generales de nuestro API:

Va apareciendo a la derecha el renderizado de nuestro API. Aparece un error, ya que faltan elementos en la estructura. En este caso, nos indica que no hemos definido las rutas. Procedemos a definir éstas:

Con esto ya tenemos nuestro API casi completo. Puede verse que hemos definido la ruta, los métodos de petición (acciones), datos para la documentación y, muy importante, los parámetros y las posibles respuestas.

Es muy importante remarcar que existe la posibilidad, como está indicado en la línea 30, de definir las entidades por separado. De esta forma facilitamos su uso, muy especialmente si las tenemos que usar más de una vez. Para ello, añadiremos una nueva seccion, llamada definitions:

Como puede verse, se definen cómodamente todas las propiedades, incluyendo enumerados. Es posible exportar el archivo, tanto en YAML como en JSON, para poder utilizarlo por nuestro equipo como contrato de servicio, o por otras herramientas, como SOAPUI.

Como nota interesante, os recomiendo echar un vistazo a los menús “Generate Server” y “Generate Client”, que nos permitirán generar código en varios lenguajes de programación. Todo un ahorro de tiempo, ¿verdad?

Os dejo varios enlaces que seguro que os resultan muy útiles:

Web oficial de YAML
Sintaxis YAML
Editor Swagger

Autor | José Manuel Morillas Navarro, Analista Programador – Soluciones Microsoft Sogeti Spain