Versionamento
O que pode mudar debaixo de você, e o que não pode.
A versão está no caminho: /api/v1/....
Mudanças aditivas entram na v1. Um campo novo numa resposta, um parâmetro opcional novo, uma rota nova, um escopo novo. Escreva clientes que ignoram campos que não conhecem, porque campos novos vão aparecer.
Qualquer coisa que remova um campo ou mude o significado dele espera a v2. As
duas rodariam lado a lado enquanto a v1 é descontinuada, com um cabeçalho
Deprecation e uma data de encerramento anunciada antes de qualquer uma das
duas significar algo.
Uma exceção
Uma vez, em outubro de 2026, a v1 perdeu campos sem esperar a v2. As cores
que o layout do Profile Studio guardava saíram das respostas de
GET /api/v1/profile/layout e GET /api/v1/profiles/{username}/layout:
color num background (o da página, o de uma seção ou o do style de um
bloco), textColor no style de um bloco e color, background e radius
num elemento text. Elas tinham chegado com o schema 2 do layout em 12 de
outubro de 2026, às 06:10 UTC, e saíram no mesmo dia, quando o texto e os
fundos passaram a seguir sempre o tema.
A regra foi deixada de lado desta vez porque esses campos ficaram menos de um
dia em produção. O schema continua 2. Um PUT que ainda os manda não é
recusado: eles são descartados e o resto é guardado. Um background que só
tinha cor vira null, e tone auto, que olhava a cor, agora olha só a
imagem.
A regra continua valendo: qualquer outra remoção espera a v2.
O que não é contrato
- O
messagede um erro. Compare pelocode. - A ordem das chaves num objeto.
- A redação exata de qualquer coisa escrita para uma pessoa ler.
As rotas do próprio site
Existem duas dúzias de handlers sob /api que não são esta API. São os do site,
moldados em torno de uma tela cada, e mudam sempre que aquela tela muda. Nenhum
deles aceita uma chave, então nada passa a depender deles por acidente.