REST API 错误返回良好实践 [英] REST API error return good practices

问题描述

我正在寻找有关从 REST API 返回错误的良好做法的指南.我正在开发一个新的 API，所以我现在可以朝任何方向发展.我的内容类型目前是 XML，但我计划在未来支持 JSON.

I'm looking for guidance on good practices when it comes to return errors from a REST API. I'm working on a new API so I can take it any direction right now. My content type is XML at the moment, but I plan to support JSON in future.

我现在添加了一些错误案例，例如客户端尝试添加新资源但已超出其存储配额.我已经在处理某些带有 HTTP 状态代码的错误情况(401 用于身份验证，403 用于授权，404 用于普通错误请求 URI).我查看了有福的 HTTP 错误代码，但 400-417 范围似乎都不适合报告特定于应用程序的错误.所以一开始我很想用 200 OK 和一个特定的 XML 有效负载返回我的应用程序错误(即.付给我们更多，你会得到你需要的存储！)但我停下来思考它，它似乎很肥皂(/吓得耸耸肩).此外，感觉就像我将错误响应分成不同的情况，因为有些是 http 状态代码驱动的，有些是内容驱动的.

I am now adding some error cases, like for instance a client attempts to add a new resource but has exceeded his storage quota. I am already handling certain error cases with HTTP status codes (401 for authentication, 403 for authorization and 404 for plain bad request URIs). I looked over the blessed HTTP error codes but none of the 400-417 range seems right to report application specific errors. So at first I was tempted to return my application error with 200 OK and a specific XML payload (ie. Pay us more and you'll get the storage you need!) but I stopped to think about it and it seems to soapy (/shrug in horror). Besides it feels like I'm splitting the error responses into distinct cases, as some are http status code driven and other are content driven.

那么行业的建议是什么?好的做法(请解释原因！)，此外，从客户端的观点来看，REST API 中的哪种错误处理可以让客户端代码的工作更轻松?

So what is the industry recommendations? Good practices (please explain why!) and also, from a client pov, what kind of error handling in the REST API makes life easier for the client code?

推荐答案

所以一开始我很想用 200 OK 和一个特定的 XML 有效负载返回我的应用程序错误(即.付给我们更多，你会得到你需要的存储！)但我停下来思考它似乎肥皂味(/耸耸肩).

So at first I was tempted to return my application error with 200 OK and a specific XML payload (ie. Pay us more and you'll get the storage you need!) but I stopped to think about it and it seems to soapy (/shrug in horror).

除非请求确实没有问题，否则我不会返回 200.在 RFC2616 中，200 表示请求已成功".

I wouldn't return a 200 unless there really was nothing wrong with the request. From RFC2616, 200 means "the request has succeeded."

如果超出客户端的存储配额(无论出于何种原因)，我将返回 403(禁止):

If the client's storage quota has been exceeded (for whatever reason), I'd return a 403 (Forbidden):

服务器理解请求，但拒绝满足它.授权无济于事，不应重复该请求.如果请求方法不是 HEAD 并且服务器希望公开请求未完成的原因，它应该在实体中描述拒绝的原因.如果服务器不希望向客户端提供此信息，则可以使用状态代码 404(未找到)代替.

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.

这告诉客户端请求没问题，但失败了(200 不做).这也让您有机会在响应正文中解释问题(及其解决方案).

This tells the client that the request was OK, but that it failed (something a 200 doesn't do). This also gives you the opportunity to explain the problem (and its solution) in the response body.

您想到了哪些其他特定的错误条件?

What other specific error conditions did you have in mind?

这篇关于REST API 错误返回良好实践的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！