El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia
HOME Mis cursos Finalizados
◄ Anterior
◄

Versionado de APIs

Siguiente ►
►

El versionado de APIs es una práctica esencial en el desarrollo de APIs RESTful. Permite a los desarrolladores introducir cambios y mejoras en una API sin interrumpir a los usuarios que dependen de versiones anteriores. En esta sección, exploraremos los conceptos clave del versionado de APIs, las diferentes estrategias de versionado y cómo implementarlas.

Conceptos Clave

  1. Compatibilidad hacia atrás: La capacidad de una API para seguir funcionando con clientes que utilizan versiones anteriores.
  2. Versionado mayor y menor: Diferenciación entre cambios que rompen la compatibilidad (versionado mayor) y cambios que no la rompen (versionado menor).
  3. Deprecación: El proceso de marcar una versión de la API como obsoleta antes de su eliminación final.

Estrategias de Versionado

Existen varias estrategias para versionar una API. A continuación, se describen las más comunes:

  1. Versionado en la URL

Esta es una de las estrategias más comunes y consiste en incluir la versión de la API en la URL. Por ejemplo:

https://api.ejemplo.com/v1/recursos

Ventajas:

  • Fácil de implementar y entender.
  • Claramente visible en la URL.

Desventajas:

  • Puede llevar a URLs largas y difíciles de manejar.
  • No es ideal para cambios menores que no rompen la compatibilidad.

  1. Versionado en el Header

Otra estrategia es incluir la versión en los headers de la solicitud HTTP. Por ejemplo:

GET /recursos HTTP/1.1
Host: api.ejemplo.com
Accept: application/vnd.ejemplo.v1+json

Ventajas:

  • Mantiene las URLs limpias.
  • Permite mayor flexibilidad en el manejo de versiones.

Desventajas:

  • Menos visible y puede ser más difícil de descubrir para los desarrolladores.
  • Requiere configuración adicional en el servidor.

  1. Versionado en el Parámetro de Consulta

También se puede incluir la versión como un parámetro de consulta en la URL. Por ejemplo:

https://api.ejemplo.com/recursos?version=1

Ventajas:

  • Fácil de implementar.
  • Claramente visible en la URL.

Desventajas:

  • Puede llevar a URLs largas y difíciles de manejar.
  • No es ideal para cambios menores que no rompen la compatibilidad.

Implementación del Versionado

A continuación, se muestra un ejemplo práctico de cómo implementar el versionado en la URL utilizando Node.js y Express.

Ejemplo de Código

const express = require('express');
const app = express();
const port = 3000;

// Middleware para manejar diferentes versiones
app.use('/v1', require('./routes/v1'));
app.use('/v2', require('./routes/v2'));

// Rutas para la versión 1
const v1Router = express.Router();
v1Router.get('/recursos', (req, res) => {
    res.json({ version: 'v1', data: 'Recursos de la versión 1' });
});
app.use('/v1', v1Router);

// Rutas para la versión 2
const v2Router = express.Router();
v2Router.get('/recursos', (req, res) => {
    res.json({ version: 'v2', data: 'Recursos de la versión 2' });
});
app.use('/v2', v2Router);

app.listen(port, () => {
    console.log(`Servidor escuchando en http://localhost:${port}`);
});

Explicación del Código

  1. Configuración del Servidor: Se configura un servidor Express en el puerto 3000.
  2. Middleware para Versiones: Se utilizan middlewares para manejar diferentes versiones de la API (/v1 y /v2).
  3. Rutas para Versiones: Se definen rutas específicas para cada versión de la API. En este caso, /v1/recursos y /v2/recursos.

Ejercicio Práctico

Ejercicio

Implementa una API con dos versiones utilizando la estrategia de versionado en la URL. La API debe tener un endpoint /productos que devuelva una lista de productos. La versión 1 debe devolver los productos en formato JSON, y la versión 2 debe devolver los productos en formato XML.

Solución

const express = require('express');
const app = express();
const port = 3000;
const xml = require('xml');

// Datos de ejemplo
const productos = [
    { id: 1, nombre: 'Producto 1', precio: 100 },
    { id: 2, nombre: 'Producto 2', precio: 200 }
];

// Middleware para manejar diferentes versiones
app.use('/v1', require('./routes/v1'));
app.use('/v2', require('./routes/v2'));

// Rutas para la versión 1
const v1Router = express.Router();
v1Router.get('/productos', (req, res) => {
    res.json(productos);
});
app.use('/v1', v1Router);

// Rutas para la versión 2
const v2Router = express.Router();
v2Router.get('/productos', (req, res) => {
    res.set('Content-Type', 'application/xml');
    res.send(xml({ productos: productos.map(p => ({ producto: p })) }));
});
app.use('/v2', v2Router);

app.listen(port, () => {
    console.log(`Servidor escuchando en http://localhost:${port}`);
});

Explicación de la Solución

  1. Datos de Ejemplo: Se define una lista de productos.
  2. Middleware para Versiones: Se configuran middlewares para manejar las versiones /v1 y /v2.
  3. Rutas para Versiones:
    • En la versión 1 (/v1/productos), se devuelve la lista de productos en formato JSON.
    • En la versión 2 (/v2/productos), se devuelve la lista de productos en formato XML utilizando el módulo xml.

Conclusión

El versionado de APIs es crucial para mantener la compatibilidad y permitir la evolución de una API sin interrumpir a los usuarios existentes. Existen varias estrategias para versionar una API, cada una con sus ventajas y desventajas. La elección de la estrategia adecuada dependerá de las necesidades específicas de tu API y de tus usuarios. En el próximo tema, exploraremos cómo documentar adecuadamente tu API para que los desarrolladores puedan utilizarla de manera efectiva.

◄ Anterior
◄
Siguiente ►
►
El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia
© Copyright 2024. Todos los derechos reservados