Histórico da Página
...
Bloco de código | ||
---|---|---|
| ||
http://fluig.totvs.com/api/v1/users http://fluig.totvs.com/api/v1.5/users http://fluig.totvs.com/api/v2/users |
Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.
Informações | ||
---|---|---|
| ||
A politica de depreciação deve definir o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e estará disponível. A politica é pode ser única para cada área de negócio mas deve estar documentada e evidente para o usuário final. |
Quando alterar a versão?
O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.
Alterações que devem gerar uma nova versão "minor":
- URIs foram removidas ou renomeadas;
- Foram removidos campos do retorno de um endpoint;
- Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
- Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
- Um novo endpoint foi adicionado a API.
Alterações que NÃO devem gerar uma nova versão "minor":
- Um novo formato de retorno é suportado pelo endpoint;
- Novas propriedades são retornadas na entidade de retorno do endpoint;
- Novos parâmetros opcionais podem ser passados para o endpoint.
Documentação
Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica devem estar documentadas na página de documentação do fluig. Além disso deve ser gerado um documento SWAGGER com as definições da API.