API - Guia de Estilo

Versionamento

286 views 05/08/2020 23/11/2020 jefersonfrancisco 0

Os endpoints da plataforma senior X suportam o versionamento de APIs.

O versionamento adotado pela plataforma senior X é feito através do header HTTP accept: Ex:

application/json;seniorx.version=2

* Onde: seniorx.version=? identifica a versão da API que se deseja invocar.

Para produtos baseados na SDL, deve-se seguir as recomendações e práticas indicadas na documentação Wiki do projeto GIT do plugin da SDL.

O ideal é evitar ao máximo versionar uma API mas, eventualmente, algumas regras de negócio e até mesmo novas implementações acabam forçando a alteração dos contratos de uma API já existente. Para estas situações, visando não quebrar a implementação dos desenvolvedore externos, esta mudança de contrato deve ser externalizada através de uma nova versão da API.

Critérios para versionamento de uma API:
– Adicionar inputs obrigatórios no payload de entrada
– Renomear ou remover campos dos payloads
– Alterar tipos de dados dos atributos
– Alterar verbos HTTP (quando aplicável) ou HTTP response codes
– Identificar algum design inconsistente (neste caso, avaliar a depreciação da API antiga ou até mesmo a criação de um novo endpoint)

Como são apresentados os endpoints públicos versionados aqui no dev.senior?
De acordo com a imagem a seguir, o endpoint aparece “duplicado” apresentando a versão entre parênteses.

Ao expandir o endpoint, o cabeçalho accept já sugere o conteúdo correto a ser utilizado para invocar aquela versão.
É importante avaliar atentamente os payloas de input e output, visto que estes poderão apresentar diferenças entre as versões.

Este artigo foi útil para você?