...

APIs Publicas são todas as APIs que podem ser acessadas por clientes externos aos times de desenvolvimento do fluig.

Erros

Mensagem padrão de erro

Todos as respostas de erro (códigos HTTP 4xx e 5xx) devem retornar uma mensagem contendo pelo menos obrigatoriamente os campos a seguir:

{
    code: "Código identificador do erro",
    helpUrl: "link para a documentação  messagedo error",
    message: "Literal no idioma da requisição descrevendo o erro para o cliente",
    logdetailedMessage: "Mensagem técnica e mais detalhada do erro"
}

• O campo code deve identificar unicamente o erro na documentação da API;
• O campo helpUrl deve apontar para diretamente para documentação do erro na API;
• O campo message deve descrever o erro de forma não técnica e pode ser usado pelos clientes para exibição ao usuário. O texto deste campo deve respeitar o idioma usado na requisição (definido pelo cabeçalho Accept-Language ou o padrão caso este não seja especificado);
• O campo detailedMessage deve descrever o erro de forma mais técnica e pode conter referências que ajudem na correção / localização do erro no contexto do servidor do fluig.
  
  

Código 4xx versus 5xx

Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.

Erros de negóciosão definidos como o cliente passando dados inválidos para o endpoint e este corretamente e intencionalmente rejeitando os dados ou requisição são aqueles causados por dados inválidos na requisiçõe ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatóriamente obrigatoriamente retornar um código HTTP 4xx. Ex: 

1. O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized
2. O cliente chamou um endpoint mas mesmo estando autenticado não possui os direitos necessários as permissões necessárias para efetuar a operação. Deve retornar o código 403 - Forbidden
3. O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existe. Deve ser retornado o código de erro 404 - Not found
4. 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 400 - Bad Request
5. O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable
6. O cliente chamou um endpoint para subir um documento mas o usuário logado passou o limite de espaço estipulado para seu perfil. Deve retornar o código 507 - Insufficiente Storage;

Erros não esperados são os erros não tratados ou não intencionais. Esse tipo de erro devesempre retornar códigos HTTP 5xx. Ex:

1. O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;
2. O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage;