Conceitos

Versionamento

Introdução do conceito de versionamento as controllers, com isso o consumidor da API poderá escolher qual versão utilizar. As versões suportadas pelo serviço sempre estarão alinhados com os releases do Korp ERP, por exemplo: 2023.2, 2023.1. Qualquer alteração na API que contenha uma quebra obrigatoriamente gera uma versão nova. Se define como quebra o seguinte:

  • Remover um endpoint (método publicado deixou de existir)

  • Remover ou renomear um campo de entrada (propriedade em payload, propriedade na URL, etc)

  • Remover ou renomear um campo de saída (propriedade no retorno)

  • Adicionar um novo campo de entrada obrigatório

  • Tornar obrigatório um campo de entrada anteriormente opcional

  • Alterando o tipo de um campo de entrada ou saída

  • Remover valores de enumerador (remover um valor de um enum)

  • Adicionar uma nova regra de validação a um campo existente

  • Alterar os requisitos de autenticação ou autorização (o endpoint precisa de uma permissão)

  • Mudança significativa na regra de negócio (mudança impactante)

Política de versões

As APIs deverão suportar pelo menos as últimas três versões.

Especificando uma versão

O consumidor deverá apontar qual versão da API que quer utilizar enviando o header X-Korp-Api-Version. Por exemplo:

curl --header "X-Korp-Api-Version:2023.1" https://gateway.korp.com.br/produtos

As requisições que não estiverem com o header X-Korp-Api-Version automaticamente utilizarão a versão do ambiente utilizado.