¿Cómo gestiona OpenAPI la obsolescencia de las API? #

En el cambiante panorama del desarrollo de software, mantener una API actualizada es fundamental. Esto suele implicar añadir nuevas funcionalidades, mejorar las existentes y, en ocasiones, eliminar funcionalidades antiguas u obsoletas. Gestionar estos cambios requiere una comunicación clara con los desarrolladores que consumen la API. OpenAPI, una especificación ampliamente adoptada para documentar API, ofrece una forma estructurada de gestionar estos cambios, incluida la obsolescencia de endpoints o funcionalidades de una API. Este artículo analiza cómo gestiona OpenAPI la obsolescencia de las API y ofrece algunas buenas prácticas para afrontar estos escenarios.

¿Qué es la obsolescencia de una API? #

La obsolescencia de una API consiste en marcar determinados endpoints, parámetros o funcionalidades como anticuados o programados para su eliminación en versiones futuras. La obsolescencia actúa como una advertencia para los desarrolladores y les permite migrar a alternativas más recientes antes de que se eliminen los elementos obsoletos. Este proceso es esencial para mantener la compatibilidad y evitar que se rompan las integraciones que dependen de la API.

Visión general de la especificación OpenAPI #

La especificación OpenAPI (OAS) es un formato estandarizado para describir API RESTful. Permite que tanto las personas como los equipos informáticos descubran y comprendan las capacidades de un servicio sin necesidad de acceder a su código fuente. Un documento OpenAPI especifica los endpoints, las operaciones, los parámetros, los formatos de solicitud y respuesta, entre otros aspectos.

OpenAPI se ha convertido en el estándar de facto para la documentación de API y es aceptado e implementado por las principales herramientas y frameworks de API, entre ellos Swagger y Postman.

Gestión de la obsolescencia en OpenAPI #

Obsolescencia de endpoints #

OpenAPI permite marcar los endpoints como obsoletos mediante el atributo deprecated. Este atributo se puede añadir al objeto de operación dentro de la definición del endpoint.

A continuación se muestra un ejemplo de cómo marcar un endpoint como obsoleto en un documento OpenAPI 3.0:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /deprecated-endpoint:
    get:
      summary: Deprecated endpoint example
      deprecated: true
      responses:
        '200':
          description: Success

En el ejemplo anterior, la solicitud GET a /deprecated-endpoint se marca como obsoleta mediante el atributo deprecated: true. De este modo, se puede informar a los consumidores de la API sobre la obsolescencia a través de la documentación generada.

Obsolescencia de propiedades de esquemas #

Además de endpoints completos, también se pueden marcar como obsoletas propiedades individuales dentro de un esquema. Por ejemplo, considera un objeto User en el que el campo username ha quedado obsoleto y se eliminará en versiones futuras.

Así se marca una propiedad como obsoleta:

components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
          deprecated: true
        email:
          type: string
        fullName:
          type: string

En esta configuración, la propiedad username del esquema User está obsoleta.

Obsolescencia de parámetros #

También puedes marcar como obsoletos parámetros de ruta, de consulta o de encabezado. Por ejemplo, para marcar como obsoleto un parámetro de consulta llamado oldParam:

paths:
  /example:
    get:
      summary: Example with deprecated query parameter
      parameters:
        - name: oldParam
          in: query
          required: false
          schema:
            type: string
          deprecated: true
      responses:
        '200':
          description: Success

En este caso, el parámetro de consulta oldParam está marcado como obsoleto.

Comunicar la obsolescencia a los consumidores de la API #

La obsolescencia no consiste únicamente en marcar elementos como anticuados; es vital comunicar estos cambios de forma eficaz a los desarrolladores que dependen de la API. A continuación se presentan algunas estrategias para garantizar una transición fluida:

Documentación #

Asegúrate de que los elementos obsoletos estén claramente indicados en la documentación de tu API. Herramientas como Swagger UI y Redoc muestran automáticamente los avisos de obsolescencia a partir de la especificación OpenAPI.

Respuestas de la API #

Incluye encabezados personalizados o información en el cuerpo para avisar a los desarrolladores cuando utilicen endpoints o funcionalidades obsoletos. Por ejemplo, puedes añadir un encabezado de respuesta como X-Deprecated-Endpoint para informar a los usuarios sobre la obsolescencia del endpoint.

responses:
  '200':
    description: Success
    headers:
      X-Deprecated-Endpoint:
        description: This endpoint is deprecated and will be removed in the future.
        schema:
          type: string

Versionado y políticas de retirada (sunset) #

Define con claridad los esquemas de versionado y las políticas de retirada (sunset). Indica cuándo se eliminarán las funcionalidades obsoletas y ofrece guías de migración para ayudar a los desarrolladores a realizar la transición sin problemas. Versionar la API (por ejemplo, de /v1/resource a /v2/resource) puede ayudar a gestionar los cambios incompatibles de forma más eficaz.

Notificaciones a los desarrolladores #

Envía anuncios o boletines sobre las obsolescencias a través de los canales en los que tu comunidad de desarrolladores esté activa. Utiliza listas de correo, foros y plataformas como GitHub o Slack para mantener una comunicación abierta y transparente.

Buenas prácticas para la obsolescencia de las API #

Ofrece alternativas #

Proporciona siempre alternativas o versiones más recientes para las funcionalidades obsoletas. Si un endpoint o un parámetro está programado para su eliminación, asegúrate de que los usuarios conozcan el reemplazo recomendado.

Período de gracia #

Ofrece un período de gracia razonable entre la declaración de obsolescencia y la eliminación. Este período da a los desarrolladores tiempo suficiente para adaptar sus implementaciones en función de las obsolescencias.

Política de obsolescencia coherente #

Adopta una política coherente de obsolescencia en toda tu organización. Define directrices claras sobre cómo, cuándo y por qué se declaran obsoletos los elementos. Asegúrate de que todos los miembros del equipo comprendan estas políticas para mantener cambios en la API fluidos y predecibles.

Registros y métricas #

Supervisa el uso de las funcionalidades obsoletas mediante registros y métricas. Comprender los patrones de uso te ayuda a tomar decisiones fundamentadas sobre la eliminación efectiva de los elementos obsoletos. Herramientas como Grafana y Prometheus pueden resultar útiles para realizar el seguimiento de las métricas de uso de la API.

Ejemplos del mundo real #

API de GitHub #

La API REST de GitHub tiene políticas de obsolescencia claras. Cuando GitHub declara obsoleta una funcionalidad de la API, lo comunica mediante la documentación, publicaciones de blog y encabezados de obsolescencia en las respuestas de la API. También proporciona calendarios para la eliminación de las funcionalidades obsoletas, lo que deja un amplio margen para la transición.

API de Google Cloud #

Las API de Google Cloud siguen políticas estrictas de versionado y obsolescencia. Ofrecen notas de versión detalladas y guías de migración que ayudan a los desarrolladores a adaptarse a los cambios. Las obsolescencias se anuncian con mucha antelación, de modo que los usuarios disponen de un plazo suficiente.

Conclusión #

La obsolescencia es un aspecto fundamental de la gestión del ciclo de vida de las API. La especificación OpenAPI ofrece funcionalidades sólidas para gestionar la obsolescencia tanto a nivel de endpoint como de parámetro o propiedad. Una comunicación clara, una documentación exhaustiva y una política de obsolescencia bien definida son elementos clave para garantizar una transición fluida a los desarrolladores que utilizan tu API. Si sigues las buenas prácticas y aprendes de los líderes del sector, podrás gestionar eficazmente las obsolescencias de las API y mantener un ecosistema de API saludable y actualizado.

Para obtener información más detallada, puedes consultar la documentación de la especificación OpenAPI oficial, explorar herramientas como Swagger y estudiar las estrategias de obsolescencia empleadas por grandes plataformas como GitHub y Google Cloud.

Al gestionar con criterio la obsolescencia de las API, te aseguras de que tu API siga siendo fiable y fácil de usar para los desarrolladores durante muchos años.

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