Pular para o conteúdo
thiagoetipadrões

Contatos

apps/api/api-versioning

121 · API & Integração · ≈ 6 min de estudo

API Versioning

Duas versões do contrato convivem na mesma API, cada uma um grupo de rotas (/v1, /v2) sobre um modelo interno único; só o mapper de cada versão muda. A versão antiga anuncia a própria aposentadoria com Deprecation, Sunset e Link e responde 410 Gone depois do sunset, enquanto o uso por versão e por cliente mostra quem ainda precisa migrar. Use quando uma mudança quebra o contrato — tipo de campo, campo renomeado, opcional que vira obrigatório.

passos
6
arquivos
4
testes
0
tecnologias
5
Infraestrutura realTypeScriptBunElysiaPostgreSQLDocker
CenárioRelaçõesComparar
Baixar cartão

Cenário

A API de transferências nasceu com valor em reais como número, status em português e data local, sem método de pagamento (tudo era PIX). A v2 passa a centavos inteiros, renomeia campos, exige method (PIX ou TED, com tarifa) e devolve instantes ISO. O app legado continua na v1 até migrar; a política publicada deprecia a v1 em 01/07/2026 e a desliga em 30/06/2027.

Planta

Fluxo
9/9
App legadogrupo /v1Deprecation, Sunset, Link410 apos o sunsetApp novogrupo /v2mapperTransferV1reais, status emportugues, data localmapperTransferV2centavos, method,tarifa, ISOModelo interno TransferPostgreSQLtransfersapi_version_usagedia, versao, cliente/v1/transfers/v2/transfers
9

9 passos — reproduza para seguir o fluxo

Como funciona

6 passos

v1 e v2 convivem sem quebrar clientes.

Esconde cada passo: lembre antes de tocar para revelar.

  1. 01

    Um único modelo Transfer e uma única tabela; mapperTransferV1 e mapperTransferV2 moldam cada contrato, e a v1 grava tudo como PIX

  2. 02

    Os reais da v1 viram centavos com checagem: zero, negativo ou fração de centavo é 422

  3. 03

    A partir da data de deprecação, toda resposta da v1 leva Deprecation: @<epoch> (RFC 9745), Sunset (RFC 8594) e Link para o guia de migração

  4. 04

    No instante do sunset a v1 passa a responder 410 Gone com o link de migração; a v2 segue igual

  5. 05

    Cada chamada soma em api_version_usage por dia, versão e cliente (x-client-id), inclusive as respondidas com 410

  6. 06

    O relógio é injetado, então os dois limites são testados no segundo exato

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

  • Cliente antigo segue funcionando até o sunset

  • Um modelo e um banco: a mudança fica só no mapper

  • Versão na URI: visível em log e cacheável

  • Uso por cliente diz quando é seguro desligar

Custos

  • Duas versões para manter e testar ao mesmo tempo

  • O modelo interno precisa comportar o que as duas versões expõem

  • URI muda a cada versão maior

  • Desligar exige que os clientes realmente migrem

apps/api/api-versioning

4 arquivos

src/

  • api_versioned.tsGrupos /v1 e /v2, cabeçalhos de deprecação, 410 e contagem de uso
  • mapper_transfer.tsOs mappers de cada versão e a conversão de reais para centavos
  • model_transfer.tsModelo interno e gravação, compartilhados pelas versões

sql/

  • 01_schema.sqlschemaTransferências e uso por versão e cliente

Executar · com Docker

  1. ./docker.sh up# sobe PostgreSQL
  2. cp .env.example .env# variáveis de ambiente
  3. bun install# dependências
  4. bun run demo# roda o cenário
  5. bun run test# integração contra o serviço real
Requisitos
BunDocker
Sobe junto
PostgreSQL

Relações

Onde ele se encaixa

Mapa
  1. API Versioning
  • Combina com3

Por que se relacionam

Combina com

Teste rápido

Qual destes combina com API Versioning?

Próximo projeto · API & IntegraçãoHTML Scraping
Esc

↑ ↓ navegarEnter abrir191 resultados