Políticas para o Construtor de API de Dados
Um conjunto de políticas rege o Construtor de API de Dados relacionado com alterações interruptivas, notificações, lançamentos e controlo de versões.
Controlo de versões e lançamentos
Uma versão no contexto do Construtor de API de Dados refere-se a todas as versões publicadas do software, identificadas pelo Major.Minor.Patch formato. Estas versões enquadram-se em três categorias: estável, alteração interruptiva e pré-visualização.
Versões estáveis
Uma versão estável do Construtor de API de Dados é retrocompatível. Retrocompatível implica que qualquer código que escreva que dependa de uma versão de um construtor de API de Dados pode adotar uma versão estável mais recente sem exigir alterações de código para manter a correção ou a funcionalidade existente.
Versões de alteração interruptiva
Uma versão de alteração interruptiva do Construtor de API de Dados não é retrocompatível. A adoção de uma versão de alteração interruptiva no código de cliente existente pode exigir alterações de código para garantir que o cliente se comporta exatamente como tinha quando direcionou para a versão anterior.
As versões de alteração interruptiva são anunciadas através do artigo da lista de alterações interruptivas e na descrição da alteração de uma versão do GitHub. A publicação de uma versão de pré-visualização/lançamento de candidatos precede versões de alteração interruptivas, a menos que as alterações corrijam problemas críticos de segurança, privacidade ou legais. Embora as versões anteriores do Construtor de API de Dados possam permanecer disponíveis na página de versões do GitHub, recomendamos que atualize para a versão mais recente, o que pode incluir correções de erros.
Versões de pré-visualização
As versões de pré-visualização do Construtor de API de Dados são identificadas com o X.Y.Z-rc esquema de controlo de versões. O -rc sufixo indica que a compilação é um "candidato à versão". As versões de pré-visualização são utilizadas para recolher comentários sobre novas funcionalidades e outras alterações.
A menos que planeemos fazer alterações significativas propositadamente a partir da última versão estável, publicamos a próxima versão de pré-visualização com tudo, desde a versão estável mais recente e novas funcionalidades de pré-visualização. A próxima atualização do Construtor de API de Dados poderá interromper algumas das novas funcionalidades de pré-visualização que adicionámos entre versões de pré-visualização. Este comportamento de interrupção significa que poderá ter de alterar o código para que tudo volte a funcionar.
As versões de pré-visualização não se destinam a utilização a longo prazo ou de produção. Quando uma nova versão estável ou de pré-visualização fica disponível, as versões de pré-visualização mais antigas poderão deixar de estar acessíveis. É melhor utilizar versões de pré-visualização apenas quando estiver a trabalhar ativamente em novas funcionalidades e estiver pronto para mudar para uma versão que não seja de pré-visualização logo após o lançamento. Se algumas funcionalidades de uma versão de pré-visualização estiverem incluídas numa nova versão estável, as restantes funcionalidades de pré-visualização serão adicionadas a uma nova versão de pré-visualização para experimentar.
Tabela de alteração de versão
Importante
Podemos introduzir uma alteração interruptiva para uma versão secundária ou de patch quando a alteração resolve erros críticos do produto, problemas legais, de segurança ou de privacidade.
| Tipo de versão | Versão Anterior | Nova Versão | Notas |
|---|---|---|---|
| Alteração Interruptiva | 1.Y.Z |
2.Y.Z |
Novas funcionalidades e correções de erros, juntamente com alterações interruptivas. |
| Estável | 1.1.Z |
1.2.Z |
Novas funcionalidades e correções de erros sem alterações interruptivas, a menos que as alterações resolvam erros críticos do produto, problemas legais, de segurança ou de privacidade. |
| Estável | 1.1.1 |
1.1.2 |
Correções de erros sem novas funcionalidades ou alterações interruptivas, a menos que as alterações resolvam erros críticos do produto, problemas legais, de segurança ou de privacidade. |
| Pré-visualizar | X.Y.1-rc |
X.Y.2-rc |
Novas funcionalidades de pré-visualização e correções de erros. (As alterações interruptivas são incluídas se a versão principal for alterada.) |
Alterações Interruptivas
Para priorizar a segurança, melhorar as funcionalidades e manter a qualidade do código, as novas versões do nosso software podem incluir alterações interruptivas. Enquanto nos esforçamos para minimizar estas alterações através de escolhas arquitetónicas cuidadosas, elas ainda podem ocorrer. Nestes casos, é prioritário anunciá-los e fornecer possíveis soluções.
Importante
Poderemos efetuar alterações sem aviso prévio se a alteração for considerada não interruptiva ou se se tratar de uma alteração interruptiva que está a ser efetuada para resolver erros críticos do produto ou problemas legais, de segurança ou de privacidade.
O que é uma mudança interruptiva?
Uma alteração interruptiva é uma modificação que requer que atualize a aplicação para evitar interrupções. No Construtor de API de Dados, as alterações interruptivas podem incluir alterações aos contratos da API REST, à geração de esquemas do GraphQL e a outros elementos que afetam a compatibilidade e a funcionalidade.
Exemplos de alteração interruptiva
Os exemplos seguintes são uma lista não anexestiva de alterações interruptivas ao construtor de API de Dados:
- Modificações do contrato da API REST
- Alterações na geração de esquemas do GraphQL
- Alterações que afetam a retrocompatibilidade
- Remoção ou mudança de nome de APIs ou parâmetros
- Alterações nos códigos de erro
- Ajustes à funcionalidade de definição de permissão
- Remoção de parâmetros permitidos, campos de pedido ou campos de resposta
- Adição de parâmetros obrigatórios ou campos de pedido sem valores predefinidos
- Modificações à funcionalidade de ponto final da API pretendida
Definição de uma alteração não sequente
Uma alteração não interruptiva refere-se a uma alteração que pode ser integrada na sua aplicação sem causar interrupções. Normalmente, as alterações não se quebram são comunicadas após a implementação. A sua aplicação deve ser concebida para processar estas alterações sem aviso prévio.
Exemplos de Alterações Não Interruptivas
Os exemplos seguintes são uma lista não independente de alterações não se separadoras ao Construtor de API de Dados:
- Introdução de novos pontos finais
- Adição de métodos a pontos finais existentes
- Incorporação de novos campos em respostas e pedidos
- Ajustes à ordem dos campos nas respostas
- Introdução de cabeçalhos de pedido opcionais
- Alterações ao comprimento dos dados e ao tamanho da resposta
- Alterações a mensagens de erro e códigos
- Correções para códigos de resposta HTTP
- Metadados adicionais em documentos OpenAPI gerados
Como comunicamos alterações interruptivas?
É prioritário informá-lo rapidamente sobre alterações interruptivas. Pode encontrar notificações de alteração interruptiva nas notas de versão das versões do Construtor de API de Dados no GitHub e no artigo da lista de alterações interruptivas dedicada.
Lista de alterações interruptivas atual
As alterações interruptivas e as descontinuações de funcionalidades são anunciadas neste artigo.
- A partir de agora, não existem alterações interruptivas