...

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ócio 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 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 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;

...

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;

Mensagens de sucesso

Mensagens de sucesso DEVEM ser retornadas para todos os códigos http 2xx e DEVEM ter pelo menos o campo content que representa o objeto resultado da operação do endpoint. Ex:

{
  content: {}
}

Mensagens de sucesso para coleções

Nos casos em que o resultado da operação do endpoint represente uma coleção além do campo content deve ser retornado o campo hasNext indicando se existe uma próxima página com mais registros para aquela coleção.

...

Mensagens de sucesso

Mensagens de sucesso DEVEM ser retornadas para todos os códigos http 2xx e DEVEM ter pelo menos o campo content que representa o objeto resultado da operação do endpoint. Ex:

{
  content: {}
}

Mensagens de sucesso para coleções

Nos casos em que o resultado da operação do endpoint represente uma coleção além do campo content deve ser retornado o campo hasNext indicando se existe uma próxima página com mais registros para aquela coleção.

{
  hasNext: true,
  content: [
    {},
    {},
    ...
  ]
}

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ócio 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 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 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

...

Parâmetros expansíveis

Todos os endpoints DEVEM respeitar e suportar os campos expansíveis. E DEVEM retornar os campos retraídos a menos que especificado na requisição atráves do parâmetro de url expand.

...