Como fazer versionamento de APIs no Express.js?

Como fazer versionamento de APIs no Express.js?

O versionamento de APIs é essencial para permitir a evolução de um sistema sem quebrar compatibilidade com versões anteriores. No Express.js, podemos fazer isso de diferentes formas.

1. Versionamento via URL

A abordagem mais comum é incluir a versão na URL:

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

// Versão 1 da API
app.get('/api/v1/usuarios', (req, res) => {
    res.json({ versao: '1.0', mensagem: 'Lista de usuários - v1' });
});

// Versão 2 da API
app.get('/api/v2/usuarios', (req, res) => {
    res.json({ versao: '2.0', mensagem: 'Lista de usuários com novos campos - v2' });
});

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

Agora, podemos acessar diferentes versões via:

• GET /api/v1/usuarios
• GET /api/v2/usuarios

2. Versionamento via Header

Outra abordagem é enviar a versão no cabeçalho da requisição:

app.get('/api/usuarios', (req, res) => {
    const versao = req.headers['accept-version'];
    if (versao === '2.0') {
        return res.json({ versao: '2.0', mensagem: 'Lista de usuários v2' });
    }
    res.json({ versao: '1.0', mensagem: 'Lista de usuários v1' });
});

Agora, o cliente pode especificar a versão no header:

Accept-Version: 2.0

3. Versionamento via Query Params

Também podemos definir a versão via parâmetro de consulta:

app.get('/api/usuarios', (req, res) => {
    const versao = req.query.versao || '1.0';
    res.json({ versao, mensagem: `Lista de usuários v${versao}` });
});

Agora, podemos chamar:

• GET /api/usuarios?versao=1.0
• GET /api/usuarios?versao=2.0

Conclusão

O versionamento de APIs no Express.js permite a evolução da aplicação sem impactar clientes que ainda usam versões antigas. A escolha da melhor abordagem depende das necessidades do projeto.

Por que o versionamento de APIs é essencial para sistemas escaláveis?

Grandes empresas como Google, Facebook e Twitter utilizam versionamento de APIs para garantir que mudanças no backend não afetem usuários que ainda dependem de versões antigas.

O versionamento bem estruturado permite que novas funcionalidades sejam adicionadas sem descontinuar rapidamente os endpoints antigos, garantindo uma transição suave para os usuários.

Algumas aplicações:

• Garantia de compatibilidade com versões antigas
• Evolução gradual de uma API
• Facilidade na implementação de novos recursos
• Redução do impacto em clientes já existentes
• Organização de mudanças na API

Dicas para quem está começando

• Escolha um método de versionamento adequado ao seu projeto.
• Utilize versionamento via URL para maior clareza na documentação.
• Considere versionamento por Header se quiser flexibilidade.
• Documente todas as versões da API corretamente.
• Evite mudanças abruptas em APIs que ainda estão em uso.

Compartilhe este tutorial