Status Codes, Content-Type e Headers

O retorno de objetos nos REST Services são automaticamente gerenciados pela plataforma, por exemplo, se um erro ocorrer o status code retornado será 500, com a mensagem de erro e um content-type correto.

Se o seu endpoint retornar um objeto, a plataforma irá retornar o seu objeto em formato JSON, com um status code 200 e content-type correto.

No entanto, pode ser necessário mudar esses Status, e você tem controle total sobre isso, veja o exemplo abaixo:

return Status.withCode(200)
          .withData(data)
          .ofContentType("application/json")
          .withHeaders({
               "x-my-header": "Hello!"
          });

O código acima, retornaria o objeto "data" em formato JSON e incluiria algumas informações no cabeçalho(Header) da resposta.

Redirect

Um outro exemplo é o uso de redirects, em certos casos, é desejado que a sua API retorne um Redirect para outra URL. A melhor forma de fazer isso é retornando um status 302 com o cabeçalho apropriado.

Veja o exemplo abaixo:

return new StatusCode(302)
        .withHeaders({ "Location": url })
        .withPlainText("Redirecting ...");

Nesse caso, a API retornaria um status 302 redirecionando a requisição para a url.

Erros

Os códigos de status têm uma função importante na hora de diferenciar erros que são provenientes de uma requisição feita de forma incorreta e de um erro de processamento do servidor.

Erros 5xx são erros de processamento no servidor(Problemas de acesso aos dados, regras de negócio, etc...), enquanto erros 4xx são erros de requisição (URL incorreta, requisição mal feita, parâmetros incorretos).

Também é possível controlar esses erros e retornar status diferenciados, por exemplo, se você esperava que um parâmetro fosse enviado pelo cliente, mas ele não foi enviado. O ideal é que sua API retorna um erro 4xx e não um erro 5xx

Veja o exemplo abaixo:

var obj = {
    "error": "error.api.missingparams",
    "message": require("inpaas.core.l10n").translate("error.api.missingparams")
};

return Status.withCode(400).withData(obj);

🚧

Status Codes

A lista de códigos de status é extensa, retornar status corretos auxiliará quem estiver se integrando com o seu aplicativo a entender os retornos e erros. Lembre-se, uma API bem construída é o primeiro passo para o sucesso de um projeto orientado a serviços.

Veja mais sobre os códigos de status em:
https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html