Erro de API REST retorna boas práticas [fechado]

Estou procurando orientação sobre boas práticas quando se trata de retornar erros de uma API REST. Estou trabalhando em uma nova API para que eu possa tomar qualquer direção no momento. Meu tipo de conteúdo é XML no momento, mas pretendo oferecer suporte a JSON no futuro.

Agora estou adicionando alguns casos de erro, como por exemplo, um cliente tenta adicionar um novo recurso, mas excedeu sua cota de armazenamento. Já estou lidando com certos casos de erro com códigos de status HTTP (401 para autenticação, 403 para autorização e 404 para URIs de solicitação incorreta). Examinei os abençoados códigos de erro HTTP, mas nenhum do intervalo 400-417 parece certo para relatar erros específicos de aplicativos. Então, no começo, fiquei tentado a retornar meu erro de aplicativo com 200 OK e uma carga XML específica (ou seja, pague-nos mais e você obterá o armazenamento de que precisa!), Mas parei para pensar sobre isso e parece que está ensaboado (/ encolher de ombros horrorizado). Além disso, parece que estou dividindo as respostas de erro em casos distintos, pois alguns são baseados no código de status http e outros são direcionados ao conteúdo.

Então, quais são as recomendações da indústria? Boas práticas (explique o porquê!) E também, de um cliente pov, que tipo de tratamento de erros na API REST facilita a vida do código do cliente?

Então, no começo, fiquei tentado a retornar meu erro de aplicativo com 200 OK e uma carga XML específica (ou seja, pague-nos mais e você obterá o armazenamento de que precisa!), Mas parei para pensar sobre isso e parece que está ensaboado (/ encolher de ombros horrorizado).

Eu não retornaria 200, a menos que realmente não houvesse nada de errado com a solicitação. De RFC2616 , 200 significa "a solicitação foi bem-sucedida".

Se a cota de armazenamento do cliente tiver sido excedida (por qualquer motivo), eu retornaria 403 (Proibido):

O servidor entendeu a solicitação, mas está se recusando a atendê-la. A autorização não ajudará e a solicitação NÃO DEVE ser repetida. Se o método de solicitação não foi HEAD e o servidor deseja tornar público o motivo pelo qual a solicitação não foi atendida, DEVE descrever o motivo da recusa na entidade. Se o servidor não desejar disponibilizar essas informações ao cliente, o código de status 404 (Não encontrado) poderá ser usado.

Isso informa ao cliente que a solicitação foi OK, mas que falhou (algo que um 200 não faz). Isso também oferece a oportunidade de explicar o problema (e sua solução) no corpo da resposta.

Que outras condições de erro específicas você tinha em mente?

Um ótimo recurso para escolher o código de erro HTTP correto para sua API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Um trecho do artigo:

Onde começar:

2XX / 3XX:

4XX:

5XX:

A principal opção é que você deseja tratar o código de status HTTP como parte da sua API REST ou não.

Ambas as formas funcionam bem. Concordo que, estritamente falando, uma das idéias do REST é que você use o código Status HTTP como parte da sua API (retorne 200 ou 201 para uma operação bem-sucedida e 4xx ou 5xx, dependendo de vários casos de erro). , não há polícia REST. Você pode fazer o que você quiser. Eu já vi APIs não REST muito mais flagrantes sendo chamadas "RESTful".

Neste ponto (agosto de 2015), recomendo que você use o código de status HTTP como parte da sua API. Agora é muito mais fácil ver o código de retorno ao usar estruturas do que era no passado. Em particular, agora é mais fácil ver o caso de retorno que não é de 200 e o corpo de respostas que não são de 200 do que no passado.

O código de status HTTP faz parte da sua API

1. Você precisará escolher cuidadosamente códigos 4xx que atendam às suas condições de erro. Você pode incluir uma mensagem de descanso, xml ou texto sem formatação como a carga útil que inclui um subcódigo e um comentário descritivo.

2. Os clientes precisarão usar uma estrutura de software que permita obter o código de status no nível HTTP. Geralmente capaz, nem sempre direto.

3. Os clientes terão que distinguir entre códigos de status HTTP que indicam um erro de comunicação e seus próprios códigos de status que indicam um problema no nível do aplicativo.

O código de status HTTP NÃO faz parte da sua API

1. O código de status HTTP sempre será 200 se seu aplicativo recebeu a solicitação e respondeu (casos de sucesso e erro)

2. TODAS as suas respostas devem incluir informações sobre "envelope" ou "cabeçalho". Normalmente algo como:

   envelope_ver: 1.0
   status: # use os códigos que desejar. Reserve um código para o sucesso.
   msg: "ok" # Uma sequência humana que reflete o código. Útil para depuração.
   data: ... # Os dados da resposta, se houver.

3. Esse método pode ser mais fácil para os clientes, pois o status da resposta está sempre no mesmo local (sem subcódigos necessários), sem limites nos códigos, sem necessidade de buscar o código de status no nível HTTP.

Aqui está um post com uma ideia semelhante: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Questões principais:

1. Certifique-se de incluir números de versão para poder alterar posteriormente a semântica da API, se necessário.

2. Documento...

Lembre-se de que existem mais códigos de status do que os definidos nas RFCs HTTP / 1.1. O registro da IANA está em http://www.iana.org/assignments/http-status-codes . Para o caso que você mencionou, o código de status 507 parece correto.

Como outros já apontaram, ter uma entidade de resposta em um código de erro é perfeitamente permitido.

Lembre-se de que os erros 5xx são do lado do servidor, ou seja, o cliente não pode alterar nada em sua solicitação para fazer com que a solicitação seja aprovada. Se a cota do cliente for excedida, isso definitivamente não é um erro do servidor, portanto, 5xx deve ser evitado.

Existem dois tipos de erros. Erros de aplicativo e erros de HTTP. Os erros de HTTP servem apenas para informar ao seu manipulador AJAX que tudo correu bem e não deve ser usado para mais nada.

5xx erro de servidor

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Success

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

No entanto, a maneira como você cria os erros do aplicativo depende de você. O Estouro de Pilha, por exemplo, envia um objeto com response, datae messagepropriedades. A resposta que acredito conter trueou falseindicar se a operação foi bem-sucedida (geralmente para operações de gravação). Os dados contêm a carga útil (geralmente para operações de leitura) e a mensagem contém metadados adicionais ou mensagens úteis (como mensagens de erro quando responsehouver false).

Sei que é extremamente tarde para a festa, mas agora, no ano de 2013, temos alguns tipos de mídia para cobrir o tratamento de erros de uma maneira distribuída (RESTful) comum. Consulte "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) e "Detalhes do problema para APIs HTTP", application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).

Acordado. A filosofia básica do REST é usar a infraestrutura da web. Os códigos de status HTTP são a estrutura do sistema de mensagens que permite que as partes se comuniquem sem aumentar a carga útil do HTTP. Eles já são códigos universais estabelecidos que transmitem o status da resposta e, portanto, para serem verdadeiramente RESTful, os aplicativos devem usar essa estrutura para comunicar o status da resposta.

Enviar uma resposta de erro em um envelope HTTP 200 é enganoso e força o cliente (consumidor da API) a analisar a mensagem, provavelmente de maneira não padronizada ou proprietária. Isso também não é eficiente - você forçará seus clientes a analisar a carga HTTP toda vez que entender o status de resposta "real". Isso aumenta o processamento, adiciona latência e cria um ambiente para o cliente cometer erros.

Modelar sua API nas 'melhores práticas' existentes pode ser o caminho a percorrer. Por exemplo, veja como o Twitter lida com códigos de erro https://developer.twitter.com/en/docs/basics/response-codes

Por favor, atenha-se à semântica do protocolo. Use 2xx para respostas bem-sucedidas e 4xx, 5xx para respostas de erro - sejam suas exceções comerciais ou outras. Se o uso do 2xx para qualquer resposta fosse o caso de uso pretendido no protocolo, eles não teriam outros códigos de status em primeiro lugar.

Não se esqueça dos erros 5xx, bem como dos erros de aplicativos.

Nesse caso, o que dizer de 409 (Conflito)? Isso pressupõe que o usuário possa resolver o problema excluindo os recursos armazenados.

Caso contrário, 507 (não totalmente padrão) também pode funcionar. Eu não usaria 200, a menos que você use 200 para erros em geral.

Se a cota do cliente for excedida, é um erro do servidor, evite 5xx nesta instância.