REST API最佳实践：如何接受参数值作为输入列表 [英] REST API Best practice: How to accept list of parameter values as input

问题描述

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

我们可能要接受两种风格但这种灵活性实际上会导致更多的混乱和头痛（可维护性，文档等）？

一个更复杂的情况是，我们希望提供更复杂的输入。例如，如果我们要允许搜索多个过滤器：

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

我们并不希望把过滤器类型（例如productType和颜色）为这样的请求名称：

<$p$p><$c$c>http://our.api.com/Search?term=pumas&productType=[\"Clothing\",\"Bags\"]&color=[\"Black\",\"Red\"]

由于我们希望把所有的滤波器输入在一起。

在年底，这是否真的重要吗？这可能是可能有这么多的JSON utils的在那里，输入类型少了点管那么多了。

我知道我们的JavaScript客户端AJAX调用的API可能AP preciate的JSON的投入，使他们的生活更轻松。

解决方案

退一步

首先，REST描述了一个URI作为通用唯一标识。有太多的人得到的URI的结构和URI是比其他人更平安赶上了。 这个说法的话说命名人鲍勃比命名他为乔更好，因为可笑 - 这两个名字得到的识别人所做的工作 URI是不是仅此而已的通用唯一的名称。

因此​​，在REST的眼睛争论是否？ID =101404，7267261] 比更舒适？ID = 101404， 7267261 或 \\产品\\ 101404,7267261 是有些徒劳。

现在，话说回来，很多时候的URI是如何构造的，通常可以作为一个RESTful服务等问题的良好指标。有你的URI一对夫妇的红旗和问题一般。

建议

1. 对同一资源的多个URI和内容位置

   
     

   我们可能要接受两种风格但这种灵活性实际上会导致更多的混乱和头痛（可维护性，文档等）？

   
   

   的URI标识的资源。每个资源应有的有一个标准URI。这并不意味着你不能有两个URI指向同一资源的但的有明确定义的方式去这样做。如果你决定同时使用JSON和列表基于格式（或任何其他形式），你需要决定这些格式是主要的规范的URI。指向相同的资源到其他所有的URI的响应应该包括 内容位置头。

   名为比喻坚持，有多个URI，就像拥有人的绰号。这是完全可以接受很多时候非常方便，但如果我用一个绰号我还是会想知道他们的全名 - 官方的方式是指该人。当有人通过他们的全名提到有人通过这种方式，Nichloas Telsa，我知道他们是在谈论我称之为尼克是同一个人。




2. 在您的URI搜索

   
     

   一个更复杂的情况是，我们希望提供更复杂的输入。例如，如果我们要允许搜索多个过滤器...

   
   

   我的经验一般的规则是，如果你的URI包含一个动词，它可能是一个迹象，一些已关闭。 URI的标识一个资源，但是他们不应该指出的什么的我们正在做的这些资源。这是HTTP或在宁静方面的工作，我们的统一接口。

   要打败名死者的比喻，在一个URI使用动词是像改变某人的名字，当你想与他们进行互动。如果我与鲍勃的互动，当我想招呼他Bob的名字不会成为BobHi。同样，当我们想搜索的产品，我们的URI结构不应该更改/产品/ ...到/搜索/...\".

回答您最初的问题

1. 关于 [101404，7267261] VS 101404,7267261 ：在这里我的建议是为了避免为简单起见，JSON语法（即不要求你的用户做URL编码，当你不真的有）。它会让你的API稍微更实用。更重要的是，正如其他人推荐，去与标准应用程序/ x-WWW的形式urlen codeD 格式，因为它可能会是最熟悉的最终用户（例如： ID [] = 101404＆放大器; ID [] = 7267261 ）。它可能不是pretty，而是pretty的URI并不一定意味着可用的URI。然而，虽然重申我的初始点，最终谈到REST时，也没关系。不要纠缠太沉重了。




2. 您的复杂的搜索的URI例子可以在非常相同的方式作为产品例如来解决。我会建议将再次在应用程序/ x-WWW的形式urlen codeD 格式，因为它已经是一个标准，很多人都熟悉。另外，我建议合并两个。

您URI ...

<$p$p><$c$c>/Search?term=pumas&filters={\"productType\":[\"Clothing\",\"Bags\"],\"color\":[\"Black\",\"Red\"]}

是URI连接codeD后，您的URI ...

<$p$p><$c$c>/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

可以转化为...

<$p$p><$c$c>/Product?term=pumas&productType[]=Clothing&productType[]=Bags&color[]=Black&color[]=Red

除了避免URL编码的要求，使事情看起来有点多标准，它现在均匀化API一点。用户知道，如果他们想获取产品或产品清单（包括被认为是基于REST的术语单一的资源），他们感兴趣的是 /产品/...的URI。

We are launching a new REST API and I wanted some community input on best practices around how we should have input parameters formatted:

Right now, our API is very JSON-centric (only returns JSON). The debate of whether we want/need to return XML is a separate issue.

As our API output is JSON centric, we have been going down a path where our inputs are a bit JSON centric and I've been thinking that may be convenient for some but weird in general.

For example, to get a few product details where multiple products can be pulled at once we currently have:

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

Should we simplify this as:

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

Or is having JSON input handy? More of a pain?

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

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

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

We don't necessarily want to put the filter types (e.g. productType and color) as request names like this:

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

Because we wanted to group all filter input together.

In the end, does this really matter? It may be likely that there are so many JSON utils out there that the input type just doesn't matter that much.

I know our JavaScript clients making AJAX calls to the API may appreciate the JSON inputs to make their life easier.

解决方案

A Step Back

First and foremost, REST describes a URI as a universally unique ID. Far too many people get caught up on the structure of URIs and which URIs are more "restful" than others. This argument is as ludicrous as saying naming someone "Bob" is better than naming him "Joe" – both names get the job of "identifying a person" done. A URI is nothing more than a universally unique name.

So in REST's eyes arguing about whether ?id=["101404","7267261"] is more restful than ?id=101404,7267261 or \Product\101404,7267261 is somewhat futile.

Now, having said that, many times how URIs are constructed can usually serve as a good indicator for other issues in a RESTful service. There are a couple of red flags in your URIs and question in general.

Suggestions

1. Multiple URIs for the same resource and Content-Location

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

   URIs identify resources. Each resource should have one canonical URI. This does not mean that you can't have two URIs point to the same resource but there are well defined ways to go about doing it. If you do decide to use both the JSON and list based formats (or any other format) you need to decide which of these formats is the main canonical URI. All responses to other URIs that point to the same "resource" should include the Content-Location header.

   Sticking with the name analogy, having multiple URIs is like having nicknames for people. It is perfectly acceptable and often times quite handy, however if I'm using a nickname I still probably want to know their full name – the "official" way to refer to that person. This way when someone mentions someone by their full name, "Nichloas Telsa", I know they are talking about the same person I refer to as "Nick".

2. "Search" in your 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...

   A general rule of thumb of mine is, if your URI contains a verb, it may be an indication that something is off. URI's identify a resource, however they should not indicate what we're doing to that resource. That's the job of HTTP or in restful terms, our "uniform interface".

   To beat the name analogy dead, using a verb in a URI is like changing someone's name when you want to interact with them. If I'm interacting with Bob, Bob's name doesn't become "BobHi" when I want to say Hi to him. Similarly, when we want to "search" Products, our URI structure shouldn't change from "/Product/..." to "/Search/...".

Answering Your Initial Question

1. Regarding ["101404","7267261"] vs 101404,7267261: My suggestion here is to avoid the JSON syntax for simplicity's sake (i.e. don't require your users do URL encoding when you don't really have to). It will make your API a tad more usable. Better yet, as others have recommended, go with the standard application/x-www-form-urlencoded format as it will probably be most familiar to your end users (e.g. ?id[]=101404&id[]=7267261). It may not be "pretty", but Pretty URIs does not necessary mean Usable URIs. However, to reiterate my initial point though, ultimately when speaking about REST, it doesn't matter. Don't dwell too heavily on it.

2. Your complex search URI example can be solved in very much the same way as your product example. I would recommend going the application/x-www-form-urlencoded format again as it is already a standard that many are familiar with. Also, I would recommend merging the two.

Your URI...

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

Your URI after being URI encoded...

/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

Can be transformed to...

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

Aside from avoiding the requirement of URL encoding and making things look a bit more standard, it now homogenizes the API a bit. The user knows that if they want to retrieve a Product or List of Products (both are considered a single "resource" in RESTful terms), they are interested in /Product/... URIs.

这篇关于REST API最佳实践：如何接受参数值作为输入列表的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！