我应该在我的 REST API 中什么时候使用信封?如果我在一个地方使用它，我应该一直使用它吗? [英] When in my REST API should I use an envelope? If I use it in one place, should I always use it?

问题描述

我正在致力于构建 RESTful Web 服务.我已经阅读了为每种机制使用 HTTP 的原则，并且在大多数情况下，比如获取资源时，它工作得很好.

I'm working on building a RESTful web service. I have read up on the principles of using HTTP for every mechanism as far as it will take you, and most of the time, like when fetching resources, it works pretty well.

但是当我需要发布某种新条目时，为了清晰和健壮性，无论客户端可能做什么，我都想提供新条目可能失败的特定验证错误.此外，还有一些特定的错误，例如，用于创建新用户的数据完全有效，但可能会使用昵称或电子邮件地址.简单地返回 409 Conflict 并不能详细说明昵称或电子邮件地址中的哪一个被占用.

But when I need to POST a new entry of some sort, in the interest of clarity and robustness, no matter what the client may do, I want to offer the particular validation errors that the new entry may have failed at. Additionally, there are specific errors where, say, the data for creating a new user is perfectly valid, but a nickname or an email address may be taken. Simply returning 409 Conflict doesn't finely enough detail which of the nickname or the email address was taken.

所以解决这个问题不是火箭科学:记录一堆特定的错误代码并返回一个有错误的对象:

So getting around this isn't rocket science: document a bunch of specific error codes and return an object with errors:

{ errors: [4, 8, 42] }

这意味着，在请求失败的情况下，我不会像 REST 哲学所期望的那样返回资源或其密钥.同样，当我返回很多资源时，我必须以某种方式将它们放入数组中.

This means that in the case of unsuccessful requests, I'm not returning the resource or its key as I may be expected to by the REST philosophy. Similarly, when I return many resources, I have to frame them in some way in an array.

所以我的问题是:如果我标准化了一个信封来用于每个请求，例如，总是有一个像 { errors, isSuccessful,内容 }?

So my question is: would I still be providing a well-behaved RESTful web service if I standardized an envelope to use for every request, such that, for example, there's always an object like { errors, isSuccessful, content }?

我以前构建了使用它的 RPC 样式的 Web 服务，但我不想制作几乎是 REST"的东西.如果作为 REST 有任何意义，我希望尽可能表现得乖一点.

I have previously built RPC-style web services that used this, but I don't want to make something that's "almost REST". If there's going to be any point to being REST, I'd want to be as well-behaved as possible.

如果答案是否定的，我认为可能是这样，我想听听它是否至少正确地解决了验证问题，以及对于此类问题的解决可能是一个很好的参考，因为大多数我发现的指南只详细介绍了简单的案例.

If the answer is "hell no", which I think it may be, I would like to hear if it's at least solving the validation problem correctly, and what a good reference for this sort of problem solving might be, because most guides I've found have only detailed the simple cases.

推荐答案

HTTP 是 你的信封.通过返回 4** 错误代码，您做的是正确的事情.

HTTP is your envelope. You're doing the right thing by returning a 4** error code.

话虽如此，在响应中使用描述性正文并没有错——事实上在HTTP RFC，大多数 HTTP 错误代码都提倡您确实返回错误发生原因的描述.例如参见 403:

Having said that, there is nothing wrong with having a descriptive body on a response – in fact in the HTTP RFC, most of the HTTP Error codes advocate that you do return a description of why the error occurred. See 403 for example:

如果请求方法不是 HEAD 并且服务器希望公开请求未完成的原因，它应该在实体中描述拒绝的原因.

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.

因此，您可以继续使用响应正文来更详细地描述错误.如果您不确定要使用的特定 HTTP 错误响应(例如多个错误)，并且您知道用户不应该像刚刚那样重复请求，我通常会回退到使用 400.

So you're okay to continue to use the body of a response for a more detailed description of the error(s). If you're unsure of the specific HTTP error response to use (e.g. multiple errors), and you know that the user should not repeat the request as they just did it, I usually fall back to using 400.

这篇关于我应该在我的 REST API 中什么时候使用信封?如果我在一个地方使用它，我应该一直使用它吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！