Em toda request deve ser informado o token no campo Authorization do Header.
O tipo de token a ser utilizado dependerá do serviço utilizado.
Na realização de chamadas em nome do usuário deve-se informar o token obtido durante o processo LTI/SSO (campo id_token).
Nas chamadas feitas em "nome próprio", deve-se informar o token obtido através do client_id e secret, que serão informados após o cadastro do parceiro na FTD.
Os serviços RESTs seguem a seguinte convenção para o status HTTP
Sucesso:
HttpCode 200
Todo sucesso retornar 200 OK, os demais status 2XX não são utilizados.
Erros do cliente:
HttpCode 400
Qualquer erro que ocorrer devido a falhas provenientes de payload do cliente, deverá retornar 400 BAD_REQUEST, inclusive chamadas que não façam sentido no estado atual do dado, como erros de conflitos de chave, por exemplo.
HttpCode 403
Qualquer erro que ocorrer devido a falhas de autenticação ou autorização, retornará 403 FORBIDDEN.
HttpCode 404
O status 404 NOT_FOUND é utilizado conforme convenção aplicada em APIs REST.
Erros do serviço:
HttpCode 500
O status 500 INTERNAL_ERROR englobará todos os erros da família 5XX. Qualquer erro sistêmico é representado pelo código 500, inclusive BAD_GATEWAY, NOT_IMPLEMENTED, TIMEOUT, etc.
Como complemento aos códigos do HTTP, nas respostas diferentes de sucesso (HttpCode 200), também será retornado um JSON, com a estrutra abaixo.
{
"code": "Um código interno de erro da aplicação, específico por microserviço",
"message": "Uma mensagem explicando o que é o erro emitido",
"details": "Descreve detalhes provenientes do erro, como a causa, se necessário. Campo opcional."
}Exemplos de erros
Erro de POST devido a campos faltando ou inválidos na request:
400 {"code": "400001","message": "Invalid payload","details": "userPrincipalName should be filled; email should be a valid email;"}
Erro de POST devido a conflito de userPrincipalName já existente:
400 {"code": "400002","message": "Conflict", "details": "userPrincipalName already exists;"}
Erro de falha de autenticação:
403 {"code": "403001","message": "Access denied"}
Erro de registro não encontrado:
404 {"code": "404001","message": "Not found"}
Erro interno:
500 {"code": "500001","message": "Internal server error"}
Erro de gateway timeout:
500 {"code": "500002","message": "Timeout"}
Erro de bad gateway:
500 {"code": "500003","message": "Internal server error"}