Versões e changelog

O v1 do caminho

https://api.fatureihoje.com/public/v1/me

O v1 é a versão do contrato, não a versão do programa. O programa por trás dela muda; o que a v1 promete, não.

Enquanto o caminho disser v1, o que já existe continua existindo, com o mesmo nome, o mesmo tipo e o mesmo significado.

O que é aditivo

Estas mudanças entram na v1 a qualquer momento, sem aviso:

• Campo novo numa resposta. A resposta pode ganhar campos que você nunca viu.
• Rota nova. Uma área que ainda não respondia passa a responder.
• Evento novo.
• Filtro novo ou parâmetro de consulta novo, sempre opcional.
• Valor novo de enum. Um campo de estado pode passar a devolver um valor que não existia.

Nenhuma delas quebra quem já integra, desde que o seu cliente siga três regras.

As três regras do cliente que não quebra

1. Ignore campo que você não conhece. Leia os campos que você usa e deixe o resto passar. Validação que recusa a resposta inteira por causa de um campo desconhecido quebra no primeiro campo novo.
2. Tolere valor de enum desconhecido. Trate o valor que você não reconhece como “outro” em vez de lançar erro. Um switch sem caso padrão é a falha mais comum aqui.
3. Não dependa do texto. A ordem dos campos do JSON e o texto de message não são contrato. O que é contrato está descrito em Erros.

O que quebra

Estas mudanças não acontecem na v1. Elas só existiriam numa /public/v2:

• remover ou renomear um campo de uma resposta;
• mudar o tipo de um campo;
• tornar obrigatório um campo que era opcional na requisição;
• deixar de aceitar um valor que era aceito;
• mudar o significado de um campo, mesmo mantendo nome e tipo;
• remover uma rota.

A trava automática

Isso não é só promessa escrita. O contrato publicado da v1 fica guardado no nosso repositório, e uma verificação automática compara o contrato do código com esse arquivo. Ela lista, campo a campo, o que sumiu, o que mudou de tipo, o que virou obrigatório e o que deixou de ser aceito, e barra a mudança antes de ela chegar à produção. Ela roda no gancho de commit de quem mexe no contrato e, principalmente, dentro do processo que gera a versão publicada da API: nenhuma versão chega à produção sem passar por ela.

Uma segunda verificação garante o outro lado: os schemas de resposta da v1 não são fechados. É o que faz “campo novo não quebra” ser verdade e não estilo de escrita, porque um schema fechado recusaria a própria resposta assim que ela ganhasse um campo.

Quando existir uma /public/v2

Ela ainda não existe, e nenhuma rota está em desativação.

Quando isso mudar, a v1 não sai do ar junto com a chegada da v2. O plano é avisar por dois caminhos:

• os cabeçalhos Deprecation e Sunset nas respostas da rota que estiver saindo, com a data;
• aviso por e-mail para os donos das chaves de API ativas.

Nenhum dos dois cabeçalhos aparece em resposta nenhuma hoje, justamente porque não há nada em desativação. O prazo de convivência entre v1 e v2 vai ser anunciado junto com a v2, aqui nesta página.

Como você fica sabendo do que muda

• Esta página. O changelog fica aqui, na seção abaixo.
• A Referência. Ela é gerada do código da API, então nunca lista rota que não existe nem esconde rota que existe. É a fonte mais atual de o que responde hoje.
• E-mail, nos casos que exigem ação sua, como uma desativação.

Se a sua integração é importante para o seu negócio, vale acompanhar a Referência de tempos em tempos. Campo novo não quebra nada, mas costuma ser exatamente o que você estava esperando.

Changelog

Cada entrada traz a data, o que mudou e se exige ação de quem já integra. A lista campo a campo do que a API responde é sempre a Referência.

v1 | a publicar

A primeira versão pública do contrato. A data entra aqui no dia em que a v1 for publicada. Não exige ação: não há versão anterior.

O que a v1 traz:

• Conta: GET /public/v1/me, com a empresa, as permissões da chave, o membro representado e o limite de chamadas.
• Clientes, com os endereços, e leads, com a tarefa de contato.
• Equipe, tarefas e agenda.
• Ordens de serviço, com os tipos de OS e as ações de situação, início, conclusão e cancelamento, e orçamentos, com envio, aprovação, recusa, cancelamento e conversão em venda ou em OS.
• Vendas, com versões, recebimentos, estornos, reagendamento de parcelas e cancelamento.
• Financeiro: lançamentos (inclusive transferência, recorrência e parcelamento), contas e categorias.
• Produtos, com variações e categorias, estoque só de leitura (saldo e extrato) e serviços, com categorias.
• Webhooks: cadastro de endpoints, segredo e rotação, ping, log de entregas, reenvio e a lista dos eventos dos últimos 30 dias, com o Catálogo de eventos.
• O que vale para todas as áreas: paginação por cursor, erros com código estável, idempotência em todo POST e limites de uso por plano.

Próximo passo

• Erros: por que code é estável e message não é.
• Visão geral: o que está no ar hoje e o que chega nas próximas fases.