REST API Best practice: How to accept list of parameter values as input
我们正在推出一个新的REST API，我想要一些关于如何格式化输入参数的最佳实践的社区意见：
现在，我们的API非常以JSON为中心(仅返回JSON)。关于我们是否想要/需要返回XML的争论是一个单独的问题。
由于我们的API输出是以JSON为中心的，我们一直在走一条路，我们的输入有点以JSON为中心，我一直在想这可能对某些人来说很方便，但总的来说很奇怪。
例如，要获得一些产品详细信息，我们可以立即提取多个产品：
1 | http://our.api.com/Product?id=["101404","7267261"] |
我们应该简化为：
1 | http://our.api.com/Product?id=101404,7267261 |
或者有JSON输入方便吗？更多的痛苦？
我们可能希望接受这两种风格，但这种灵活性是否会导致更多的混乱和头痛(可维护性，文档等)？
更复杂的情况是我们想要提供更复杂的输入。例如，如果我们想在搜索上允许多个过滤器：
1 | http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]} |
我们不一定要将过滤器类型(例如productType和颜色)作为请求名称，如下所示：
1 | http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"] |
因为我们想要将所有过滤器输入组合在一起。
最后，这真的很重要吗？可能有很多JSON实用程序，输入类型并不重要。
我知道我们的JavaScript客户端对API进行AJAX调用可能会欣赏JSON输入以使他们的生活更轻松。
退一步
首先，REST将URI描述为通用唯一ID。有太多人陷入了URI的结构，哪些URI比其他URI更"安静"。这个说法和说"命名某人"鲍勃比命名他"乔"更好的说法是荒谬的 - 这两个名字都得到了"识别一个人"的工作。 URI只不过是一个普遍唯一的名称。
所以在REST眼中争论
现在，已经说过，很多时候如何构造URI通常可以作为RESTful服务中其他问题的良好指标。您的URI和问题中有一些红色标记。
建议
同一资源和
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的所有响应都应包含
坚持使用名称类比，拥有多个URI就像为人们设置昵称。这是完全可以接受的，而且通常非常方便，但是如果我使用昵称，我仍然可能想知道他们的全名 -"官方"方式来引用那个人。这样当有人用他们的全名"Nichloas Telsa"提到某人时，我知道他们正在谈论我称之为"尼克"的同一个人。
您的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的工作或宁静的术语，我们的"统一界面"。
要击败名称类比死，在URI中使用动词就像在想要与他们交互时更改某人的名字。如果我和鲍勃互动，当我想对他说嗨时，鲍勃的名字不会成为"BobHi"。同样，当我们想要"搜索"产品时，我们的URI结构不应该从"/ Product / ..."更改为"/ Search / ..."。
回答你的初步问题
关于
您的复杂搜索URI示例可以与产品示例完全相同的方式解决。我建议再次使用
你的URI ......
1 | /Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]} |
URI编码后的URI ...
1 | /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 |
可以转化为......
1 | /Product?term=pumas&productType[]=Clothing&productType[]=Bags&color[]=Black&color[]=Red |
除了避免URL编码的要求并使事情看起来更标准之外，它现在使API有点均匀化。用户知道如果他们想要检索产品或产品列表(两者都被认为是RESTful术语中的单个"资源")，他们对
将值列表作为URL参数传递的标准方法是重复它们：
大多数服务器代码会将其解释为值列表，尽管许多服务器代码具有单值简化，因此您可能需要查看。
定界值也可以。
如果您需要将JSON发送到服务器，我不喜欢在URL中看到它(这是一种不同的格式)。特别是，URL具有大小限制(实际上，如果不是理论上的话)。
我看到一些RESTful执行复杂查询的方式有两个步骤：
第一：
我想你可以做两种方式
或者我最喜欢的是：
您可以使用超媒体作为RestFul WS的应用程序状态(HATEOAS)属性的引擎，并执行一个调用
第二
当您必须对网址调用进行查询时。我建议再次使用HATEOAS。
1)拨打
2)拨打
3)(使用HATEOAS)打电话给`http://our.api.com/term/pumas/productType/ - >接收所有服装可能网址的网址 - >打电话给你想要的(衣服和包包) - >收到可能的颜色网址 - >拨打你想要的颜色
您可能需要查看RFC 6570.此URI模板规范显示了许多URL如何包含参数的示例。
第一种情况：
正常的产品查找看起来像这样
所以我认为最佳实践将是你这样做
第二个案例
使用查询字符串参数进行搜索 - 这样很好。我很想将术语与AND和OR结合使用，而不是使用
PS这可能是主观的，所以做你觉得舒服的事情。
将数据放入URL的原因是链接可以粘贴在站点上/在用户之间共享。如果这不是问题，请务必使用JSON / POST。
编辑：反思我认为这种方法适合具有复合键的实体，但不适合多个实体的查询。
我会支持nategood的答案，因为它已经完成，似乎满足了你的需求。不过，我想添加一条关于识别多个(1个或多个)资源的评论：
这样做，你：
使客户复杂化
通过强制他们将您的响应解释为一个数组，如果我提出以下请求，这对我来说是违反直觉的：
创建冗余API
使用一个API获取所有产品，使用上面的一个获得1个或多个产品。由于您不应该为了UX而向用户显示超过1页的详细信息，我相信拥有1个以上的ID将毫无用处并且纯粹用于过滤产品。
它可能不是那么有问题，但您要么必须通过返回单个实体(通过验证您的响应是否包含一个或多个实体)或让客户端管理它来自己处理这个问题。
例
我想订购Amazing的书。我确切地知道它是哪本书，我在导航恐怖书时在列表中看到它：
选择第二本书后，我被重定向到详细说明列表中书籍部分的页面：
1 2 3 4 5 6 7 8 | -------------------------------------------- Book #1 -------------------------------------------- Title: The return of the amazing monster Summary: Pages: Publisher: -------------------------------------------- |
或者只是在页面上给我这本书的全部细节？
1 2 3 4 5 6 7 | --------------------------------- The return of the amazing monster --------------------------------- Summary: Pages: Publisher: --------------------------------- |
我的看法
当获取此资源的详细信息时，我建议在保证unicity时使用路径变量中的ID。例如，下面的API提供了多种获取特定资源详细信息的方法(假设产品具有唯一ID，并且该产品的规范具有唯一名称，您可以自上而下导航)：
1 2 | /products/{id} /products/{id}/specs/{name} |
当你需要超过1个资源时，我会建议从更大的集合中过滤。对于同一个例子：
1 | /products?ids= |
当然，这是我的意见，因为它没有强加。