[包子分享]REST API Best practices: Where to put parameters?

在上一篇博客中,包子为您解说了REST 设计风格的理论概念,相信有很多同学读完以后会有很多实际的问题需要进一步探讨。在这里,包子为大家转载了一个比较热门的最佳设计实践问题:如何设计REST风格的URI?从上篇文章里,我们知道URI是HTTP实现下的REST 资源ID。URI一般包含了指向资源的路径,以及参数来指定请求获取的特定资源状态。那么到底什么应该是属于URI路径的一部分,而什么又该放入URI呢?这是一个值得大家思考的设计实践。

原文链接http://stackoverflow.com/questions/4024271/rest-api-best-practices-where-to-put-parameters

Question

from: Kalle Gustafsson

A REST API can have parameters in at least two ways:
  As part of the URL-path (i.e. /api/resource/parametervalue )
  As a query argument (i.e. /api/resource?parameter=value )

What is the best practice here? Are there any general guidelines when to use 1 and when to use 2?

Real world example: Twitter uses query parameters for specifying intervals. (http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321)

Would it be considered better design to put these parameters in the URL path?

Answer

from: Tor Valamo

There are several types of "parameters" to a request, and you should take this into account.

Now let's look at the different places where these parameters could go.

Generally you want State to be set in headers or cookies, depending on what type of state information it is. I think we can all agree on this. Use custom http headers (X-My-Header) if you need to.

Similarly, Content only has one place to belong, which is in the request body, either as query strings or as http multipart and/or JSON content. This is consistent with what you receive from the server when it sends you content. So you shouldn't be rude and do it differently.

Locators such as "id=5" or "action=refresh" or "page=2" would make sense to have as a URL path, such as mysite.com/article/5/page=2 where partly you know what each part is supposed to mean (the basics such as article and 5 obviously mean get me the data of type article with id 5) and additional parameters are specified as part of the URI. They can be in the form of page=2, or page/2 if you know that after a certain point in the URI the "folders" are paired key-values.

Filters always go in the query string, because while they are a part of finding the right data, they are only there to return a subset or modification of what the Locators return alone. The search in mysite.com/article/?query=Obama (subset) is a filter, and so is /article/5?order=backwards (modification).

Think about what it does, not just what it's called! If "view" determines output format, then it is a filter (mysite.com/article/5?view=pdf) because it returns a modification of the found resource rather than homing in on which resource we want. If it instead decides which specific part of the article we get to see (mysite.com/article/5/view=summary) then it is a locator.

Remember, narrowing down a set of resources is filtering. Locating something specific within a resource is locating... duh. Subset filtering may return any number of results (even 0). Locating will always find that specific instance of something (if it exists). Modification filtering will return the same data as the locator, except modified (if such a modification is allowed).

更多设计实践

感谢Kalle同学的详尽解答。那么以后呢包子也会为大家带来更多的设计实践分享,请大家继续关注吧。

博客推送