Cuando empecé en el mundo laboral, conocía las APIs REST solo a nivel práctico y superficial gracias a que lo había estudiado y practicado durante mi etapa en el instituto. Sin embargo, desconocía aspectos fundamentales como su documentación formal, diseño, ciclo de vida y todo lo que implica construir una API bien pensada desde cero.
Recuerdo también cuando de forma rudimentaria perdía horas usando Word o Excel para documentar mis APIs. Servían … pero no me ofrecían la flexibilidad que necesitaba ni una forma estandarizada de comunicar claramente su estructura.
A lo largo de los proyectos en los que he venido participando, he conocido herramientas y enfoques más robustos y es parte de lo que voy a compartir en este artículo. Es probable que varios de estos conceptos ya los conozcas y los estés usando, me refiero al enfoque API First para el diseño de contratos OpenAPI.
Hoy en día, el desarrollo de APIs es esencial en cualquier arquitectura moderna. Sin embargo, en muchos casos, los equipos empiezan desarrollando directamente el backend y dejan la documentación y el contrato OpenAPI para el final. Esto conlleva muchas veces a que ocurran fricciones, más aún si es un proyecto mediano o grande donde deben colaborar varios equipos de forma paralela: Frontend, QA, DevOps, Seguridad, etc.
Aquí es donde entra el concepto que quiero abordar hoy: API First, una técnica vital al desarrollar APIs. En mi día a día, he venido aplicándolo y he comprobado que trae muchas ventajas comparada con otro enfoque denominado Code First.
¿Qué es API First?
API First es un enfoque de desarrollo que consiste en priorizar el diseño de una API, en las etapas tempranas de un proyecto de software (antes del desarrollo del backend, frontend, infraestructura, etc).
Se puede aplicar a cualquier tipo de APIs sin importar el protocolo o estilo, es decir, puede aplicarse a APIs REST, SOAP, GraphQL, gRPC, etc, siempre y cuando la regla sea: primero diseñamos la API, y luego la desarrollamos. En este artículo me centraré en APIs REST.
¿Qué es OpenAPI?
OpenAPI (OAS) es la especificación que permite definir la sintaxis y estructura de un API HTTP de manera estandarizada, la cual puede ser en formato YAML o JSON.
Proporciona un lenguaje agnóstico e independiente de la tecnología o el lenguaje de programación, lo que facilita que cualquier persona o sistema comprenda todas las capacidades de la API descrita bajo este estándar.
¿Qué es un contrato OpenAPI?
Es un documento elaborado siguiendo la Especificación OpenAPI. En este contrato se especifica la estructura de la API, es decir, el detalle de sus componentes tales como: endpoints (rutas con los métodos HTTP), query params (parámetros de consulta), Path params (parámetros de ruta), headers (cabeceras), Request Body (cuerpo de las solicitudes en caso aplique), casos de éxito y de error, etc.
Con este contrato se pude saber claramente todas las capacidades de la API: es decir, cómo funciona, qué operaciones están disponibles, cómo se deben usar, qué tipos de datos espera recibir o enviar, etc.
Y el tener este contrato definido claramente desde el inicio de un proyecto, trae muchas ventajas. Algunas de ellas las describo a continuación:
Ventajas de API First
- Los equipos pueden trabajar simultáneamente. Es decir, sin necesidad de que se tenga que esperar a que la API esté terminada por el equipo de Backend, los Frontend pueden empezar su desarrollo porque gracias al contrato ya saben cómo integrarse. Además, el equipo de QA puede ir creando sus casos de prueba basados en lo que se espera de la API. También, el equipo de seguridad puede empezar a revisar y proponer medidas de seguridad con antelación. El equipo de DevOps también puede ir preparando lo suyo en paralelo, ya que se tiene claro el ‘mapa’ de la API desde el principio.
- Reduce el tiempo de desarrollo, por lo tanto, también los costos: Tener una API bien definida desde el inicio, sirve como base o plantilla de diseño y desarrollo para futuras APIs.
- Se reducen los riesgos de fallos en ambiente productivo, debido a que el tener un diseño de API en etapas tempranas, puede ser sometido a escrutinio por equipos diferentes.
Swagger: implementación de OpenAPI
Swagger es la implementación más conocida del estándar OpenAPI, y proporciona todo un ecosistema de herramientas gratuitas y de pago (como Swagger UI, Swagger Editor, Swagger Codegen, etc) las cuales son útiles al trabajar con APIs RESTful basadas en la especificación OpenAPI. En la siguiente sección usaremos Swagger Editor como apoyo para crear un contrato OpenAPI.
En su página se puede encontrar la documentación completa y ejemplos de cómo diseñar un contrato OpenApi: https://swagger.io/docs/specification/v3_0/about/.
Ejemplo guiado: Diseño de un contrato OpenAPI para un API de Gestión de Tickets
Escenario del sistema propuesto
Imaginemos que debemos desarrollar el Backend para la gestión de Tickets en una empresa de soporte técnico que atiende incidentes de usuarios dentro de una empresa. El sistema debe permitir que se creen tickets para reportar problemas. También, ciertos usuarios podrán actualizar el estado de los tickets (NEW, OPEN, IN_PROGRESS, RESOLVED, CLOSED). Este Backend en algún momento será consumido por una aplicación web y mobile.
Para este caso, seguiremos el enfoque API First, para diseñar el contrato OpenAPI usando OpenAPI como estándar y, Swagger como herramienta para el diseño, validación y visualización.
Endpoints principales
POST /tickets– Crear un nuevo ticket de soporte.GET /tickets– Obtener la lista de tickets registrados.GET /tickets/{id}– Obtener la información detallada de un ticket.PUT /tickets/{id}– Actualizar los datos de un ticket existente. Requiere enviar todos los campos incluso sin cambios-PATCH /tickets/{id}– Actualizar los datos de un ticket existente. Es una actualización parcial.DELETE /tickets/{id}– Eliminar un ticket (por ejemplo, si se creó por error).
Versionado de APIs
En el diseño de apis existe una práctica llamada API versioning, la cual permite administrar los cambios que sucede en una API a lo largo del tiempo, con la finalidad de facilitar su evolución manteniendo retrocompatibilidad, coexistencia de versiones, migración gradual, etc. Hay varias estrategias pero la más común suele ser el path versioning, es decir, el uso de un prefijo en la URL que identifica a la versión. En nuestro caso, nuestra API estará versionada desde el inicio usando el prefijo /v1. Y si posteriormente queremos cambiar la estructura o el modelo, podríamos exponer una nueva versión /v2, y ambas podrían coexistir activas durante la trancisión de una a otra. Esta es una práctica común en la industria del desarrollo de software.
Por lo tanto, los endpoints quedarían de la siguiente manera:
| Operation (método) | Path (ruta) | Descripción |
|---|---|---|
| POST | /v1/tickets | Crear un nuevo ticket de soporte. |
| GET | /v1/tickets | Obtener la lista de tickets registrados. |
| GET | /v1/tickets/{id} | Obtener los detalles de un ticket específico. |
| PUT | /v1/tickets/{id} | Actualizar los datos de un ticket existente. Requiere enviar todos los campos incluso sin cambios |
| PATCH | /v1/tickets/{id} | Actualizar los datos de un ticket existente. Es una actualización parcial. |
| DELETE | /v1/tickets/{id} | Eliminar un ticket. |
Uso de Swagger Editor
Swagger Editor es una herramienta gratuita en línea, de la familia de Swagger, que incluye un editor de código para diseñar contratos OpenAPI. Mediante esta interfaz visual podremos ver en tiempo real cómo va quedando la API, así como también posibles errores que surjan durante el diseño. Es como un IDE online para documentación OpenAPI.
URL de la herramienta: https://editor.swagger.io/
Apenas ingresemos a la URL de Swagger Editor, se nos muestra una API de ejemplo muy completo, el cuál también es útil para comprender a primera vista cómo se compone una API en el estándar OpenAPI.
Documentación de Swagger para OpenAPI
Toda la información para diseñar contratos bajo la especificación OpenAPI se encuentra en la documentación de Swagger en http://swagger.io/docs/specification/v3_0/about/.
Diseño del Contrato OpenAPI
En el link siguiente pueden encontrar el contrato OpenAPI en formato YAML para resolver el escenario propuesto. En este contrato se han utilizado los componentes más comunes y frecuentes que se pueden encontrar en muchas APIs reales.
https://github.com/luisguisadocloud/ticket-system-open-api-contract/blob/main/openapi.yaml
De una forma superficial describo las partes que conforman el contrato:
- Encabezado del contrato: Versión y metadatos.
- Documentación externa y tags.
- Paths y Operations: Cada uno de los endpoints de la API se define en esta sección: el método HTTP (POST, GET, PUT, DELETE, PATCH, etc), parámetros, respuestas y payloads esperados por cada endpoint.
- requestBody: Contiene la descripción del recurso con el que se está operando, ya sea para crear, actualizar, etc.
- responses: Contiene las posibles respuestas HTTP del endpoint: éxito (201), error de cliente (4xx), error de servidor (5xx), etc.
- Sección de componentes: components: Es la seccion que permite colocar definiciones comunes para que sean reutilizables y así evitar duplicidad de código.
La siguiente es la vista del contrato al visualizarlo en Swagger Editor (Swagger UI embebido):
Este contrato OpenAPI ha sido diseñado siguiendo la documentación oficial de la página de Swagger. En la parte 2 de este artículo, desglosaré cada sección del contrato y explicaré paso a paso su estructura.
Adicionalmente colocaré el link directo a la documentación oficial para que puedas contrastar y ampliar la información, y aplicarlo en tus propios proyectos.
Para facilitar futuras actualizaciones y mantener este contrato OpenAPI alineado con el contenido de este artículo, he publicado su versión completa en un repositorio de GitHub. Allí podré realizar ajustes o mejoras sin necesidad de modificar constantemente esta entrada del blog. Puedes consultarlo aquí: https://github.com/luisguisadocloud/ticket-system-open-api-contract
