Versionamiento de APIs 2026

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

El versionamiento de APIs permite evolucionar interfaces sin afectar a usuarios y clientes existentes.

Descripción general

El versionamiento de APIs es la gestión deliberada de cambios en una interfaz a lo largo del tiempo. Aplica por igual a REST APIs, esquemas GraphQL y servicios gRPC. El objetivo es introducir nuevas funcionalidades y correcciones sin romper clientes existentes. Las REST APIs suelen usar versionamiento en la ruta o en encabezados, GraphQL se basa en evolución de esquemas y deprecación, mientras que gRPC trabaja con Protobuf y versionamiento semántico. Independientemente del enfoque, los cambios deben categorizarse, comunicarse y documentarse. Una estrategia clara de versionamiento es un elemento central en la gestión del ciclo de vida de APIs y la estabilidad a largo plazo de una plataforma.

Componentes clave

Cambios compatibles e incompatibles

Un cambio compatible añade nuevas funcionalidades sin afectar a clientes existentes. Los ejemplos incluyen campos nuevos opcionales, endpoints adicionales o nuevos filtros. Un cambio incompatible altera el comportamiento existente, como eliminar campos, cambiar campos obligatorios o renombrar endpoints. Los cambios incompatibles requieren una nueva versión o al menos una migración cuidadosa.

Versionamiento de REST APIs

En REST APIs, URI Versioning y Header Versioning son las estrategias más comunes. URI Versioning utiliza rutas como /v1/products y es especialmente amigable con caché. Header Versioning transmite la versión a través de un encabezado como api-version: 1 o Accept: application/vnd.shop.v2+json. Content Negotiation es flexible pero más complejo.

Evolución de esquemas en GraphQL

GraphQL no utiliza versionamiento clásico en la ruta. En su lugar, el esquema evoluciona gradualmente. Se pueden añadir nuevos campos y tipos sin romper queries existentes. Los campos obsoletos se marcan con la directiva @deprecated. Los clientes deciden por sí mismos cuándo migrar a nuevos campos.

Versionamiento de gRPC y Protobuf

gRPC utiliza Protocol Buffers para definir mensajes. Se pueden añadir nuevos campos siempre que tengan números de campo cuidadosamente asignados. Los clientes antiguos ignoran campos desconocidos, los nuevos pueden trabajar con valores por defecto. El versionamiento semántico ayuda a comunicar releases Major, Minor y Patch.

Versionamiento semántico

El versionamiento semántico utiliza el formato Major.Minor.Patch. Major representa cambios incompatibles, Minor nuevas características compatibles y Patch correcciones de errores. Para APIs externas, a menudo solo se comunica públicamente la versión Major para mantener la complejidad baja para los usuarios.

Deprecación y migración

Cuando una versión o un campo ya no deba ser soportado, lo marcas como deprecated. Para GraphQL usas @deprecated, para REST encabezados como Deprecation o Sunset. Documenta la migración, informa a los usuarios con tiempo y establece una fecha clara de fin de vida.

Versionamiento en la documentación

La documentación debe estar disponible para cada versión, incluyendo changelog y guía de migración. Los usuarios deben identificar qué cambios trae una nueva versión y qué acciones son necesarias para migrar.

Caché y versionamiento

El versionamiento en la ruta es particularmente fácil de cachear porque cada versión tiene su propia URL. Con Header Versioning o GraphQL, los cachés deben configurarse para considerar las diferencias relevantes. De lo contrario, pueden ocurrir impactos de caché incorrectos.

Monitoreo y análisis de uso

Supervisa qué versiones se están utilizando. Así puedes determinar cuándo las versiones antiguas pueden desactivarse de forma segura. Rate Limiting y logging por versión ayudan a identificar uso y problemas.

API Governance

En organizaciones más grandes, API Governance regula cómo se gestionan las versiones. Los estándares para versionamiento, deprecación, comunicación y documentación aseguran consistencia entre múltiples equipos y APIs.

Ejemplo práctico

Una empresa ofrece una REST API y una GraphQL API. Se introduce un cambio incompatible en los datos de dirección en la REST API.

REST API v1:

GET /v1/customers/42
{
  "id": 42,
  "name": "Musterfirma",
  "address": "Musterstraße 12, 10115 Berlin"
}

REST API v2:

GET /v2/customers/42
{
  "id": 42,
  "name": "Musterfirma",
  "address": {
    "street": "Musterstraße 12",
    "zip": "10115",
    "city": "Berlin",
    "country": "DE"
  }
}

Evolución del esquema GraphQL:

type Customer {
  id: ID!
  name: String!
  address: String @deprecated(reason: "Use addressObject instead")
  addressObject: Address
}

type Address {
  street: String!
  zip: String!
  city: String!
  country: String!
}

En el caso de GraphQL, el cliente puede migrar gradualmente de address a addressObject sin cambiar la versión de API en la ruta. En REST, el cliente cambia de v1 a v2.

IRC-Security.de

Cybersecurity Artikel und Tutorials

FAQ: Versionamiento de APIs

Continúa con el camino de aprendizaje sobre APIs

El siguiente artículo en el camino de aprendizaje sobre APIs aborda Idempotencia en el diseño de APIs: Webhooks y ejemplos prácticos — por qué las operaciones idempotentes son esenciales para APIs confiables.

Fuentes

1. https://www.rfc-editor.org/rfc/rfc9110
2. https://graphql.org/learn/best-practices/
3. https://protobuf.dev/programming-guides/proto3/

Lecturas recomendadas sobre desarrollo de APIs

Si quieres profundizar en versionado de APIs, diseño de APIs y arquitectura de software, te recomendamos los siguientes libros:

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert