REST API最佳实践:如何接受参数值列表作为输入

我们正在推出一个新的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输入方便吗？更多的痛苦？

我们可能希望接受这两种风格,但这种灵活性是否会导致更多的混乱和头痛(可维护性,文档等)？

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

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

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

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

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

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

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

1> nategood..：

---

退一步

首先,REST将URI描述为通用唯一ID.有太多人陷入了URI的结构,哪些URI比其他URI更"安静". 这个说法和说"命名某人"鲍勃比命名他"乔"更好的说法一样荒谬 - 这两个名字都得到了"识别一个人"的工作. URI只不过是一个普遍唯一的名称.

因此,在REST的眼中,争论是否?id=["101404","7267261"]更加宁静,?id=101404,7267261或者\Product\101404,7267261有些徒劳无益.

现在,已经说过,很多时候如何构造URI通常可以作为RESTful服务中其他问题的良好指标.您的URI和问题中有一些红色标记.

建议

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

我们可能希望接受这两种风格,但这种灵活性是否会导致更多的混乱和头痛(可维护性,文档等)？

URI标识资源.每个资源都应该有一个规范的URI.这并不意味着您不能将两个URI指向同一个资源,但是有明确定义的方法可以执行此操作.如果您决定同时使用JSON和基于列表的格式(或任何其他格式),则需要确定哪些格式是主要的规范 URI.对指向相同"资源"的其他URI的所有响应都应包含Content-Location标头.

坚持使用名称类比,拥有多个URI就像为人们设置昵称.这是完全可以接受的,而且通常非常方便,但是如果我使用昵称,我仍然可能想知道他们的全名 - "官方"方式来引用那个人.这样当有人用他们的全名"Nichloas Telsa"提到某人时,我知道他们正在谈论我称之为"尼克"的同一个人.

您的URI中的"搜索"

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

我的一般经验法则是,如果您的URI包含动词,则可能表示某些内容已关闭.URI的标识资源,但是他们不应该指出什么我们正在做的这些资源.这是HTTP的工作或宁静的术语,我们的"统一界面".

要击败名称类比死,在URI中使用动词就像在想要与他们交互时更改某人的名字.如果我和鲍勃互动,当我想对他说嗨时,鲍勃的名字不会成为"BobHi".同样,当我们想要"搜索"产品时,我们的URI结构不应该从"/ Product/..."更改为"/ Search/...".

回答你的初步问题

关于["101404","7267261"]vs 101404,7267261:我的建议是为了简单起见避免使用JSON语法(即不要求用户在不需要时进行URL编码).这将使您的API更有用.更好的是,正如其他人所建议的那样,使用标准application/x-www-form-urlencoded格式,因为它可能是最终用户最熟悉的(例如?id[]=101404&id[]=7267261).它可能不是"漂亮",但Pretty URIs并不一定意味着可用的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 感兴趣.

---

想要跟进并注意,并不总是支持`[]`语法(尽管它很常见,甚至可能违反了URI规范).一些HTTP服务器和编程语言更喜欢重复名称(例如`productType = value1&productType = value2`).

---

它必须非常大(参见http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers),但是,是的,最多在极端情况下,您可能需要使用请求的正文.发布数据检索查询是RESTafarians喜欢讨论的事情之一.

---

邮政请求中的输入内容如何？我想知道我们是否要更新资源，那么以标准格式在正文中发送查询/过滤器和数据是否是一种不好的做法？例如 如果我想使用api`/ user /`并在正文中更改与用户有关的数据，我将发送带有{q`的{{q：{}，d：{}}}与用户查询将在数据库和d中查询为已修改数据。

2> Kathy Van St..：

---

将值列表作为URL参数传递的标准方法是重复它们:

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

大多数服务器代码会将其解释为值列表,尽管许多服务器代码具有单值简化,因此您可能需要查看.

定界值也可以.

如果您需要将JSON发送到服务器,我不喜欢在URL中看到它(这是一种不同的格式).特别是,URL具有大小限制(实际上,如果不是理论上的话).

我看到一些RESTful执行复杂查询的方式有两个步骤:

POST 您的查询要求,接收ID(实质上是创建搜索条件资源)

GET 搜索,引用上面的ID

如果需要,可以选择删除查询要求,但请注意它们的要求可供重用.

---

谢谢凯西.我想我和你在一起,并不喜欢在URL中看到JSON.但是,我不喜欢为搜索做一个帖子,这是一个固有的GET操作.你能指出一个例子吗？

3> Diego Dias..：

---

第一:

我想你可以做两种方式

http://our.api.com/Product/ :如果你只想要一条记录

http://our.api.com/Product :如果你想要所有记录

http://our.api.com/Product/, :正如詹姆斯建议的那样,可以选择一个选项,因为在Product标签之后出现的是一个参数

或者我最喜欢的是:

您可以使用Hypermedia作为 RestFul WS 的应用程序状态(HATEOAS)属性的引擎,并执行一个http://our.api.com/Product应该返回等效URL http://our.api.com/Product/并在此之后调用它们的调用.

第二

当您必须对网址调用进行查询时.我建议再次使用HATEOAS.

1)打个电话 http://our.api.com/term/pumas/productType/clothing/color/black

2)打个电话 http://our.api.com/term/pumas/productType/clothing,bags/color/black,red

3)(使用HATEOAS)打电话给` http://our.api.com/term/pumas/productType/ - >接收所有服装可能网址的网址 - >打电话给你想要的(衣服和包包) - >收到可能的颜色网址 - >拨打你想要的颜色

4> Darrel Mille..：

---

您可能想查看RFC 6570.此URI模板规范显示了url如何包含参数的许多示例.

---

@MikePost既然IETF已经转向了"标准跟踪"文档的两步成熟过程,我希望6570能够再继续这样做几年,然后再转向"互联网标准".https://tools.ietf.org/html/rfc6410规范非常稳定,有许多实现并且被广泛使用.

5> James Westga..：

---

第一种情况:

正常的产品查找看起来像这样

http://our.api.com/product/1

所以我认为最佳实践将是你这样做

http://our.api.com/Product/101404,7267261

第二个案例

使用查询字符串参数进行搜索 - 这样很好.我很想将术语与AND和OR结合使用而不是使用[].

PS这可能是主观的,所以做你觉得舒服的事情.

将数据放入URL的原因是链接可以粘贴在站点上/在用户之间共享.如果这不是问题,请务必使用JSON/POST.

编辑:反思我认为这种方法适合具有复合键的实体,但不适合多个实体的查询.

---

当然,在这两个示例中,尾随的`/`不应该存在,因为URI会寻址资源,而不是集合.

---

我总是在REST中使用HTTP动词来执行特定的操作，这就是指导方针：GET：检索/读取对象，POST创建对象，PUT更新现有对象和DELETE删除对象。因此，我不会使用POST来检索内容。如果我想要一个特定的对象列表（过滤器），我将使用url参数中的列表进行GET（用逗号分隔似乎很好）