El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
HOME Els meus cursos Finalitzats
◄ Anterior
◄

Versionat d'APIs

Següent ►
►

El versionat d'APIs és un aspecte crucial en el disseny i desenvolupament d'APIs RESTful. Permet als desenvolupadors introduir canvis i millores en una API sense trencar la compatibilitat amb les aplicacions que ja l'estan utilitzant. En aquesta secció, explorarem els conceptes clau del versionat d'APIs, les diferents estratègies de versionat i com implementar-les.

Conceptes Clau

  • Compatibilitat cap endavant i cap enrere: La compatibilitat cap endavant es refereix a la capacitat d'una API de funcionar amb versions futures dels clients. La compatibilitat cap enrere es refereix a la capacitat d'una API de funcionar amb versions anteriors dels clients.
  • Versions majors i menors: Les versions majors solen introduir canvis que trenquen la compatibilitat, mentre que les versions menors solen ser compatibles cap enrere i cap endavant.

Estratègies de Versionat

Hi ha diverses estratègies per versionar una API. A continuació, es presenten les més comunes:

  1. Versionat en l'URI

Aquesta és una de les estratègies més comunes i consisteix a incloure la versió de l'API en l'URI. Per exemple:

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

Avantatges:

  • Fàcil de comprendre i implementar.
  • Clarament visible en les peticions.

Desavantatges:

  • Pot resultar en URIs llargues i menys elegants.
  • Pot requerir canvis significatius en els clients quan es fa una actualització major.

  1. Versionat en els Headers

En aquesta estratègia, la versió de l'API s'especifica en els headers de la petició HTTP. Per exemple:

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

Avantatges:

  • Manté les URIs netes i elegants.
  • Permet canvis més flexibles i granulars.

Desavantatges:

  • Pot ser menys visible i intuïtiu per als desenvolupadors.
  • Requereix una configuració addicional en els clients per enviar els headers correctament.

  1. Versionat en els Paràmetres de la Query

En aquesta estratègia, la versió de l'API s'especifica com un paràmetre en la query de la URI. Per exemple:

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

Avantatges:

  • Fàcil d'implementar i comprendre.
  • Flexible per a canvis menors.

Desavantatges:

  • Pot resultar en URIs llargues i menys elegants.
  • Pot ser menys intuïtiu per als desenvolupadors.

Implementació del Versionat

A continuació, es mostra un exemple pràctic de com implementar el versionat en l'URI utilitzant Node.js i Express:

Exemple de Codi

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

// Versió 1 de l'API
app.get('/v1/recursos', (req, res) => {
    res.json({ message: 'Aquesta és la versió 1 de l\'API' });
});

// Versió 2 de l'API
app.get('/v2/recursos', (req, res) => {
    res.json({ message: 'Aquesta és la versió 2 de l\'API' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Servidor escoltant en el port ${PORT}`);
});

Explicació del Codi

  1. Configuració del servidor: Es crea una aplicació Express.
  2. Definició de les rutes: Es defineixen dues rutes diferents per a les versions 1 i 2 de l'API.
  3. Resposta de les rutes: Cada ruta retorna un missatge diferent per indicar la versió de l'API.
  4. Inici del servidor: El servidor escolta en el port especificat.

Exercici Pràctic

Exercici

Implementa una API amb dues versions utilitzant l'estratègia de versionat en els headers. La versió 1 ha de retornar un missatge de benvinguda i la versió 2 ha de retornar un missatge de benvinguda amb el nom de l'usuari.

Solució

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

app.use(express.json());

app.get('/recursos', (req, res) => {
    const version = req.headers['accept'];
    if (version === 'application/vnd.exemple.v1+json') {
        res.json({ message: 'Benvingut a la versió 1 de l\'API' });
    } else if (version === 'application/vnd.exemple.v2+json') {
        const name = req.query.name || 'usuari';
        res.json({ message: `Benvingut a la versió 2 de l'API, ${name}` });
    } else {
        res.status(400).json({ error: 'Versió no suportada' });
    }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Servidor escoltant en el port ${PORT}`);
});

Explicació de la Solució

  1. Configuració del servidor: Es crea una aplicació Express i es configura per acceptar JSON.
  2. Definició de la ruta: Es defineix una única ruta /recursos.
  3. Gestió de versions: Es comprova el header Accept per determinar la versió de l'API.
  4. Resposta de les rutes: Es retorna un missatge diferent segons la versió especificada en el header.
  5. Inici del servidor: El servidor escolta en el port especificat.

Conclusió

El versionat d'APIs és essencial per mantenir la compatibilitat i permetre l'evolució de les APIs. Hem explorat diverses estratègies de versionat i hem vist exemples pràctics de com implementar-les. Amb aquesta base, estaràs preparat per gestionar el versionat de les teves pròpies APIs RESTful de manera efectiva.

◄ Anterior
◄
Següent ►
►
El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
© Copyright 2024. Tots els drets reservats