¿Qué son los links de OpenAPI?

¿Qué son los links de OpenAPI? #

En la web actual, tan interconectada, es fundamental lograr una integración fluida y sin fricciones entre distintos servicios. Una de las especificaciones más extendidas para diseñar API es OpenAPI, antes conocida como Swagger. OpenAPI no solo describe la estructura y el funcionamiento de una API, sino que también facilita comprender, probar y automatizar las interacciones con ella. Una característica destacable de OpenAPI que ayuda a crear estos sistemas bien integrados son los links. Pero ¿qué son exactamente y cómo mejoran la experiencia con la API? Veamos en detalle el concepto de los links de OpenAPI.

Comprender OpenAPI #

Antes de profundizar en los links, conviene tener una base sólida sobre OpenAPI. OpenAPI es una especificación para definir API que permite a personas y máquinas descubrir y comprender las capacidades de un servicio sin acceder al código fuente ni a documentación adicional. La fuerza de OpenAPI reside en su capacidad para describir:

  • Los endpoints disponibles (/users, /pets, etc.).
  • Las operaciones de cada endpoint (GET, POST, PUT, DELETE, etc.).
  • Los parámetros de entrada y salida, incluidos su formato y sus tipos.
  • Los métodos de autenticación.
  • La información de contacto, la licencia, los términos de servicio y otros metadatos.

La documentación de OpenAPI suele expresarse en YAML o JSON y se puede visualizar o explorar con herramientas como Swagger UI, Postman o Redoc.

OpenAPI 3.0 introdujo una nueva característica conocida como links. Inspirados en el concepto de links de las API RESTful Hypermedia, los links de OpenAPI ofrecen una forma de definir relaciones y navegación entre las distintas operaciones de una API. En esencia, los links permiten determinar de forma dinámica qué operaciones posteriores se pueden realizar a partir de las respuestas de operaciones anteriores.

Según la especificación OpenAPI, un link es una anotación dentro de una respuesta de la API que define cómo obtener más información o realizar otras acciones a partir de esa respuesta. Se puede pensar en ellos como metadatos accionables.

Por ejemplo, cuando una llamada a /users devuelve una lista de usuarios, cada usuario de esa lista puede incluir un link para obtener más detalles sobre ese usuario concreto mediante una llamada a /users/{userId}.

Los links de OpenAPI se parecen a las relaciones de las bases de datos relacionales: ayudan a los clientes a navegar por una red de endpoints de la API.

Un link de OpenAPI suele tener las siguientes propiedades:

  • operationRef/operationId: una referencia a la operación que el cliente debe seguir.
  • parameters: un mapeo de los parámetros necesarios para invocar la operación correspondiente. Pueden ser valores fijos, expresiones o valores extraídos de la respuesta.
  • requestBody: representa el cuerpo de la solicitud si la operación enlazada lo requiere.
  • description: una breve explicación del link.
  • server: una lista opcional de servidores que se usarán para la operación enlazada.

A continuación se muestra un ejemplo de un link de OpenAPI en formato YAML:

paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: A paged array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          links:
            GetUserById:
              operationId: getUser
              parameters:
                userId: '$response.body#/id'
              
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUser
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

En este ejemplo, cuando el cliente recibe una lista de usuarios desde /users, puede seguir el link GetUserById para obtener los detalles de un usuario concreto mediante userId.

Los links ofrecen una forma comprensible por programas de navegar entre distintos endpoints y operaciones. Ayudan a definir las relaciones entre operaciones, lo que facilita a los desarrolladores entender la estructura y el flujo de la API.

Mejor documentación #

Las relaciones entre las llamadas a la API quedan documentadas de forma explícita, y no solo implícita. Esto da lugar a una documentación más clara y completa, que puede ser decisiva para incorporar a nuevos desarrolladores o a integradores externos.

Mayor automatización y mejores herramientas #

Las herramientas automatizadas pueden aprovechar los links para ofrecer un flujo de interacción más fluido. Por ejemplo, una herramienta como Postman puede usar los links para guiar a los usuarios a través de una serie de llamadas relacionadas a la API, lo que reduce las búsquedas manuales y los posibles errores.

Fomenta la coherencia del diseño #

Incluir links en el diseño de una API invita a reflexionar sobre cómo se relacionan sus distintas partes. Esto puede traducirse en un comportamiento más coherente y predecible de la API, algo beneficioso tanto para quienes la desarrollan como para quienes la consumen.

Integración más sencilla con hypermedia #

Para las API que buscan seguir los principios RESTful, en particular HATEOAS (Hypermedia As The Engine Of Application State), los links son un paso hacia la creación de API verdaderamente guiadas por hypermedia. Aunque no sustituyen por completo los controles de hypermedia de formatos como HAL o JSON-LD, los links de OpenAPI son un punto de partida valioso.

Implementar links en OpenAPI implica los siguientes pasos:

  1. Identificar las operaciones relacionadas: determina qué operaciones se relacionarán mediante links. Por ejemplo, una operación POST que crea un recurso y una operación GET que obtiene los detalles de ese recurso.

  2. Definir los objetos link: en tu especificación OpenAPI, define los objetos link dentro de la sección de respuestas de una operación. Estos links describirán cómo pasar de la operación actual a una relacionada.

  3. Mapear los parámetros: asegúrate de mapear correctamente los parámetros entre operaciones. Usa expresiones para extraer los datos necesarios de las respuestas.

  4. Probar tus implementaciones: utiliza herramientas como Swagger UI, Postman o scripts personalizados para comprobar que los links funcionan como se espera y que la navegación por la API fluye con naturalidad.

Ejemplo real: la API de GitHub #

Un ejemplo real de API que se beneficia de un sistema similar a los links es la API de GitHub. Por ejemplo, al obtener las incidencias de un repositorio, cada incidencia contiene URL hacia sus comentarios, etiquetas, etc. Aunque no usa explícitamente los links de OpenAPI, el concepto de ofrecer punteros navegables es similar.

A continuación se muestra un ejemplo conceptual alineado con los links de OpenAPI:

paths:
  /repos/{owner}/{repo}/issues:
    get:
      summary: List repository issues
      parameters:
      - name: owner
        in: path
        required: true
        schema:
          type: string
      - name: repo
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A list of issues
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Issue'
          links:
            GetIssue:
              operationId: getIssue
              parameters:
                owner: '$request.path.owner'
                repo: '$request.path.repo'
                issue_number: '$response.body#/number'
              
/components/schemas/Issue:
  type: object
  properties:
    number:
      type: integer
    title:
      type: string
    body:
      type: string
    ...

  /repos/{owner}/{repo}/issues/{issue_number}:
    get:
      summary: Get a single issue
      operationId: getIssue
      parameters:
      - name: owner
        in: path
        required: true
        schema:
          type: string
      - name: repo
        in: path
        required: true
        schema:
          type: string
      - name: issue_number
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The issue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'

Conclusión #

Los links de OpenAPI son un componente fundamental para crear diseños de API navegables y comprensibles. Al definir relaciones entre las distintas operaciones de una API, los links ofrecen una navegación mejorada, una mejor documentación, más automatización, coherencia en el diseño y una integración más sencilla con enfoques guiados por hypermedia.

Para quienes buscan diseñar API modernas, escalables y pensadas para los desarrolladores, aprovechar los links de OpenAPI será sin duda un paso en la dirección correcta. Al diseñar tu próxima API, considera cómo los links podrían aportar orientación y contexto útiles a tus clientes, y explora las diversas herramientas y la documentación disponibles en sitios como OpenAPI Initiative para ayudarte a empezar.

Recuerda que el objetivo final es lograr que las API sean más intuitivas, expresivas y fáciles de usar, y los links de OpenAPI son una potente característica para alcanzarlo.

Última actualización: 21 de mayo de 2024.

Este sitio web no está afiliado a la OpenAPI Initiative.