REST API 最佳实践 : How to accept list of parameter values as input

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改进这个问题？更新问题，以便 editing this post 提供事实和引用来回答它.

4年前关闭。




Improve this question




我们正在推出一个新的 REST API，我希望社区能就我们应该如何格式化输入参数的最佳实践提供一些意见:

现在，我们的 API 非常以 JSON 为中心(仅返回 JSON)。关于我们是否想要/需要返回 XML 的争论是一个单独的问题。

由于我们的 API 输出以 JSON 为中心，我们一直在走一条输入有点以 JSON 为中心的道路，我一直认为这对某些人来说可能很方便，但总的来说很奇怪。

例如，要获取一些可以一次提取多个产品的产品详细信息，我们目前拥有:

http://our.api.com/Product?id=["101404","7267261"]

我们是否应该将其简化为:

http://our.api.com/Product?id=101404,7267261

或者是否有方便的 JSON 输入？更痛苦？

我们可能希望同时接受这两种风格，但这种灵 active 真的会导致更多的困惑和头痛(可维护性、文档等)吗？

更复杂的情况是我们想要提供更复杂的输入。例如，如果我们想在搜索中允许多个过滤器:

http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}

我们不一定要将过滤器类型(例如 productType 和 color)作为请求名称，如下所示:

http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]

因为我们想将所有过滤器输入组合在一起。

最后，这真的重要吗？可能有这么多 JSON 实用程序，输入类型并不重要。

我知道我们的 JavaScript 客户端对 API 进行 AJAX 调用可能会喜欢 JSON 输入，以使他们的生活更轻松。

Answer 1

退后一步

首先，REST 将 URI 描述为一个普遍唯一的 ID。太多人被 URI 的结构所困扰，哪些 URI 比其他 URI 更“安静”。 这个论点就像说一个人叫“鲍勃”比叫他“乔”更好——这两个名字都完成了“识别一个人”的工作。 URI 只不过是一个普遍唯一的名称。

所以在 REST 的眼中，争论是否 ?id=["101404","7267261"]比 ?id=101404,7267261 更安静或 \Product\101404,7267261有点徒劳。

现在，话虽如此，很多时候 URI 的构造方式通常可以很好地指示 RESTful 服务中的其他问题。通常，您的 URI 和问题中有几个危险信号。

建议

同一资源的多个 URI 和 Content-Location

We may want to accept both styles but does that flexibility actually cause more confusion and head aches (maintainability, documentation, etc.)?

URI 标识资源。每个资源都应该有 一个 规范的 URI。这并不意味着您不能让两个 URI 指向同一个资源，但是有明确定义的方法可以做到这一点。如果您决定同时使用 JSON 和基于列表的格式(或任何其他格式)，您需要确定这些格式中的哪一种是主要的规范 URI。对指向相同“资源”的其他 URI 的所有响应都应包含 Content-Location header .

坚持名称类比，拥有多个 URI 就像给人们起了昵称。这是完全可以接受的，而且通常很方便，但是如果我使用昵称，我可能仍然想知道他们的全名——指代那个人的“官方”方式。这样，当有人提到某人的全名“Nichloas Telsa”时，我知道他们说的是我称为“Nick”的同一个人。

在您的 URI 中“搜索”

A more complex case is when we want to offer more complex inputs. For example, if we want to allow multiple filters on search...

我的一般经验法则是，如果您的 URI 包含动词，则可能表明某些事情已关闭。 URI 标识了一个资源，但是它们不应该表明我们正在对该资源做什么。这就是 HTTP 的工作，或者说是我们的“统一接口(interface)”。

为了打败名字类比，在 URI 中使用动词就像在你想与某人交互时更改某人的名字。如果我与 Bob 互动，当我想跟 Bob 打招呼时，他的名字不会变成“BobHi”。同样，当我们要“搜索”产品时，我们的 URI 结构不应从“/Product/...”更改为“/Search/...”。

回答你最初的问题

关于["101404","7267261"]对比 101404,7267261 :为了简单起见，我的建议是避免使用 JSON 语法(即，当您不需要时，不要要求您的用户进行 URL 编码)。它会让你的 API 更有用一点。更好的是，正如其他人所建议的那样，使用标准 application/x-www-form-urlencoded格式，因为您的最终用户可能最熟悉它(例如 ?id[]=101404&id[]=7267261 )。它可能不是“漂亮的”，但漂亮的 URI 并不一定意味着可用的 URI。但是，重申一下我最初的观点，最终在谈到 REST 时，这并不重要。不要过多地关注它。

您的复杂搜索 URI 示例可以通过与您的产品示例非常相似的方式来解决。我建议去 application/x-www-form-urlencoded再次格式化，因为它已经是许多人熟悉的标准。另外，我建议将两者合并。

你的 URI...

/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}    

URI 编码后的 URI...

/Search?term=pumas&filters=%7B%22productType%22%3A%5B%22Clothing%22%2C%22Bags%22%5D%2C%22color%22%3A%5B%22Black%22%2C%22Red%22%5D%7D

可以转化为...

/Product?term=pumas&productType[]=Clothing&productType[]=Bags&color[]=Black&color[]=Red

除了避免 URL 编码的要求并使事情看起来更标准之外，它现在使 API 同质化了一点。用户知道，如果他们想要检索产品或产品列表(在 RESTful 术语中两者都被视为单个“资源”)，他们会对 /Product/... 感兴趣。 URI。