Histórico da Página
...
- helpUrl: link para a documentação do errorerro;
- details: Uma lista de objetos de erro (recursiva) com mais detalhes sobre o erro principal.
...
O cliente chamou o endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de error erro 400 - Bad Request;
O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable.
...
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 recebera 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.
...