Políticas para o construtor de API de Dados
Um conjunto de políticas rege o construtor de API de Dados relacionado a alterações interruptivas, notificações, versões e controle de versão.
Controle de versão e versões
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 . Essas versões se enquadram em três categorias: estável, alteração interruptiva e visualização.
Versões estáveis
Uma versão estável do construtor de API de Dados é compatível com versões anteriores. Compatível com versões anteriores implica que qualquer código que você escrever 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 interruptivas
Uma versão de alteração interruptiva do Construtor de API de Dados não é compatível com versões anteriores. A adoção de uma versão de alteração interruptiva no código do cliente existente pode exigir alterações de código para garantir que o cliente se comporte exatamente como fez ao direcionar a versão anterior.
Versões de alteração interruptivas são anunciadas por meio 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 do candidato precede versões de alteração interruptivas, a menos que as alterações corrijam problemas críticos de segurança, privacidade ou legal. Embora as versões anteriores do Construtor de API de Dados possam permanecer disponíveis na página versões do GitHub, recomendamos que você atualize para a versão mais recente, o que pode incluir correções de bugs.
Versões prévias
As versões prévias do construtor de API de Dados são identificadas com o X.Y.Z-rc esquema de controle de versão. O -rc sufixo indica que o build é um "candidato à liberação". Versões prévias são usadas para coletar comentários sobre novos recursos e outras alterações.
A menos que planejemos fazer alterações significativas da última versão estável, publicaremos a próxima versão prévia com tudo, desde a versão estável mais recente e os novos recursos de visualização. A próxima atualização do Construtor de API de Dados pode interromper alguns dos novos recursos de visualização que adicionamos entre versões prévias. Esse comportamento de falha significa que talvez seja necessário alterar o código para que as coisas funcionem novamente.
Versões prévias não são destinadas para uso de longo prazo ou produção. Quando uma nova versão estável ou prévia fica disponível, versões prévias mais antigas podem não estar mais acessíveis. É melhor usar versões prévias somente quando você estiver trabalhando ativamente em novos recursos e estiver pronto para mudar para uma versão não prévia logo após o lançamento. Se alguns recursos de uma versão prévia forem incluídos em uma nova versão estável, os recursos restantes da versão prévia serão adicionados a uma nova versão prévia para você experimentar.
Tabela de alteração de versão
Importante
Podemos introduzir uma alteração interruptiva em uma versão secundária ou de patch quando a alteração resolver bugs críticos do produto, questões legais, de segurança ou de privacidade.
| Tipo de liberação | Versão anterior | Nova versão | Observações |
|---|---|---|---|
| Alteração Significativa | 1.Y.Z |
2.Y.Z |
Novos recursos e correções de bugs, juntamente com quaisquer alterações interruptivas. |
| Estável | 1.1.Z |
1.2.Z |
Novos recursos e correções de bugs sem alterações interruptivas, a menos que as alterações resolvam bugs críticos do produto, questões legais, de segurança ou de privacidade. |
| Estável | 1.1.1 |
1.1.2 |
Correções de bugs sem novos recursos ou alterações interruptivas, a menos que as alterações resolvam bugs críticos do produto, questões legais, de segurança ou de privacidade. |
| Versão Prévia | X.Y.1-rc |
X.Y.2-rc |
Novos recursos de visualização e correções de bugs. (Alterações interruptivas serão incluídas se a versão principal for alterada.) |
Alterações de quebra
Para priorizar a segurança, aprimorar os recursos e manter a qualidade do código, novas versões do nosso software podem incluir alterações interruptivas. Embora nos esforcemos para minimizar essas mudanças por meio de escolhas arquitetônicas cuidadosas, elas ainda podem ocorrer. Nesses casos, fazemos com que seja uma prioridade anunciá-los e fornecer possíveis soluções.
Importante
Podemos fazer alterações sem aviso prévio se a alteração for considerada não interruptiva ou se for uma alteração interruptiva sendo feita para resolver bugs críticos do produto ou questões legais, de segurança ou de privacidade.
O que é uma alteração interruptiva?
Uma alteração interruptiva é uma modificação que exige que você atualize seu aplicativo para evitar interrupções. No construtor de API de Dados, as alterações interruptivas podem incluir alterações em contratos de API REST, geração de esquema GraphQL e outros elementos que afetam a compatibilidade e a funcionalidade.
Exemplos de alteração interruptiva
Os exemplos a seguir são uma lista inesgotativa de alterações interruptivas no construtor de API de Dados:
- Modificações de contrato da API REST
- Alterações na geração de esquema GraphQL
- Alterações que afetam a compatibilidade com versões anteriores
- Remoção ou renomeação de APIs ou parâmetros
- Alterações nos códigos de erro
- Ajustes na funcionalidade de definição de permissão
- Remoção de parâmetros permitidos, campos de solicitação ou campos de resposta
- Adição de parâmetros obrigatórios ou campos de solicitação sem valores padrão
- Modificações na funcionalidade de ponto de extremidade de API pretendida
Definição de uma alteração sem interrupção
Uma alteração não interruptiva refere-se a uma alteração que pode ser integrada ao aplicativo sem causar interrupções. As alterações sem interrupção normalmente são comunicadas após a implementação. Seu aplicativo deve ser projetado para lidar com essas alterações sem aviso prévio.
Exemplos de alteração não interruptiva
Os exemplos a seguir são uma lista não completa de alterações não interruptivas no construtor de API de Dados:
- Introdução aos novos pontos de extremidade
- Adição de métodos a pontos de extremidade existentes
- Incorporação de novos campos em respostas e solicitações
- Ajustes na ordem de campo dentro das respostas
- Introdução aos cabeçalhos de solicitação opcionais
- Alterações no tamanho e no tamanho da resposta dos dados
- Alterações em mensagens de erro e códigos
- Correções em códigos de resposta HTTP
- Metadados extras em documentos OpenAPI gerados
Como comunicamos alterações interruptivas?
Fazemos disso uma prioridade para informá-lo prontamente sobre alterações interruptivas. Você pode encontrar notificações de alteração interruptivas 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 dedicadas.
Lista de alterações interruptivas atuais
Alterações interruptivas e desativações de recursos são anunciadas neste artigo.
- A partir de agora, não há alterações interruptivas