Política de compatibilidade de APIe políticas de descontinuação

Política de compatibilidade

Compatibilidade com versões anteriores ou mudanças simples

Inclusão de um URI que pode ampliar um recurso de API existente

Normalmente, esta mudança é segura. No entanto, é necessário levar em consideração as estruturas cliente mais populares e que podem gerar códigos conflitantes com essa mudança. Os exemplos a seguir são tipos de mudanças que podem prejudicar o código gerado pelo cliente.

• Consideremos a API existente /v1.0/foo/bar. O gerador de código pode gerar GetBar como um método de cliente. Caso uma nova API seja introduzida, /v1.0/foo/{param}, em que {param} é uma sequência arbitrária, o gerador de código pode gerar o novo método do cliente como GetFoo(String param). Essa mudança pode causar uma mudança drástica no cliente, porque a lógica que estava integrada em GetBar não é mais chamada.
• Um caminho atual /v1.0/foo/bar pode resultar nos códigos gerados pelo cliente GetBar e GetBarAsync. A inclusão de uma API /v1.0/foo/Async resulta em conflito com esse código gerado.

Inclusão de um método de HTTP em uma interface de API

Essa mudança é considerada segura, desde que a carga útil da solicitação observada antes da mudança continue existindo e tenha o mesmo comportamento. É possível incluir campos opcionais no corpo da solicitação de uma API existente ou como parâmetros de sequências de consultas.

Inclusão de cabeçalhos de solicitação opcionais

Essa mudança é considerada segura, desde que a solicitação existente antes da mudança continue a responder da mesma maneira.

Inclusão de um valor permitido em uma política existente

Os modelos de API usam sequências para representar as propriedades que permitem o uso de uma lista restrita de valores. Por exemplo, em um recurso, type pode ser documentado para criar a lista atual de tipos de recursos. Espera-se que o cliente use uma sequência genérica para esses tipos, em vez de usar a desserialização restrita de um tipo enum bem definido. Um recurso que aceita uma propriedade com vários valores possíveis pode ser aprimorado para permitir mais valores. Esses novos valores podem introduzir novas propriedades e regras de validação correspondentes. Um cliente deve se assegurar de não fazer validações com base em valores de enum não existentes, por exemplo, fazendo uma solicitação com um valor inválido de enum e esperando uma resposta de erro.

Os valores de propriedade existentes continuam a suportar comportamentos existentes. Qualquer código de cliente que contenha, por exemplo, uma lógica de ramificação sobre o tipo de recurso, continua a funcionar como anteriormente.

Inclusão de campos e/ou cabeçalhos opcionais em uma resposta

A qualquer momento, é possível incluir campos e cabeçalhos opcionais em uma resposta de API. O cliente deve se ajustar a essas mudanças.

Alterando uma mensagem de erro e descrições de recursos na resposta de API

O campo messageId em uma mensagem de erro é considerado inalterável e deve sempre abranger a lista definida de condições ou casos de erro. A descrição associada a essa mensagem pode mudar, sem que haja alteração no significado semântico da mensagem para um usuário.

Os clientes não devem construir suas lógicas com base no atributo messageDescription.

Aumentando o escopo de um ID de mensagem de erro

O campo messageId faz referência a uma ou mais condições de erro. A qualquer momento, é possível ampliar esse messageId de forma a abranger mais condições de erro. No entanto, as ampliações desse tipo devem ser lógicas e não arbitrárias. As novas condições de erro devem estar estritamente relacionadas a uma condição de erro existente que é coberta por esta mensagem.

Cabeçalhos e erros de limite de taxa

Os limites de taxas podem ser ajustados nos terminais de API durante o ciclo de vida da API sem exigir uma atualização de versão.

Os clientes que recebem o código de status de HTTP 429, informando que há um excesso de solicitações, devem fazer ajustes.

Alterações que afetam o processamento da mensagem

Remoção ou renomeação de um terminal de recurso de API ou método de HTTP

Esse tipo de mudança afeta todos os clientes que usam a API e não é permitido, a menos que seja justificada por uma forte necessidade de segurança. Cada esforço é feito para evitar tal mudança.

Remoção ou renomeação de valores enum

Os valores de enum podem ser incluídos, mas não removidos.

Alteração do type de um campo

Em geral, o type de um campo não deve mudar. No entanto, caso a implementação da API possa aceitar o type anterior e responder com o type anterior, essa mudança é considerada compatível com versões anteriores.

Alterando o comportamento visível das solicitações existentes

Se, anteriormente, uma solicitação resultou em determinada ação ou resposta, esse comportamento deve continuar. A única exceção são as extensões que podem ser feitas em um contrato existente na forma de novas mensagens de erro, códigos de status de HTTP e campos de solicitação ou resposta.

Política de descontinuação