我正在寻找一种将搜索表示为RESTful URL的合理方法。

设置：我有两个模型，汽车和车库，汽车可以放在车库中。所以我的网址看起来像：

/car/xxxx
  xxx == car id
  returns car with given id

/garage/yyy
  yyy = garage id
  returns garage with given id

汽车可以单独存在（因此/ car），也可以存在于车库中。例如，代表给定车库中的所有汽车的正确方法是什么？就像是：

/garage/yyy/cars     ?

车库yyy和zzz中的汽车联合怎么样？

代表具有特定属性的汽车的搜索的正确方法是什么？说：告诉我所有带有4门的蓝色轿车：

/car/search?color=blue&type=sedan&doors=4

还是应该改用/ cars？

在那里使用“搜索”似乎不合适-有什么更好的方法/术语？应该只是：

/cars/?color=blue&type=sedan&doors=4

搜索参数应该是PATHINFO还是QUERYSTRING的一部分？

简而言之，我正在寻找有关跨模型REST URL设计和搜索的指南。

[更新]我喜欢贾斯汀的答案，但他没有涵盖多领域搜索的情况：

/cars/color:blue/type:sedan/doors:4

或类似的东西。我们如何去

/cars/color/blue

多领域的情况？

对于搜索，请使用查询字符串。这是完全RESTful的：

/cars?color=blue&type=sedan&doors=4

常规查询字符串的一个优点是它们是标准的并且被广泛理解，并且可以从表单获取中生成。

在REST风格的漂亮的URL设计是用来显示基于结构的资源（类似目录的结构，日期：文章/ 2005/5/13，对象和它的属性，..），斜线/表示分层结构，使用-id来代替。

层次结构

我个人更喜欢：

/garage-id/cars/car-id
/cars/car-id   #for cars not in garages

如果用户删除/car-id零件，它将带来cars预览-直观。用户完全知道他在树上的什么位置，在看什么。他从第一眼就知道车库和汽车是有联系的。/car-id也表示它属于不同/car/id。

正在搜寻

searchquery是可以的，只有您的偏好，应该考虑什么。有趣的部分是加入搜索时出现的（见下文）。

/cars?color=blue;type=sedan   #most prefered by me
/cars;color-blue+doors-4+type-sedan   #looks good when using car-id
/cars?color=blue&doors=4&type=sedan   #I don't recommend using &*

或基本上任何不是斜线的东西，如上所述。
公式：/cars[?;]color[=-:]blue[,;+&]，*虽然我不会使用该&符号，因为乍一看它无法从文本中识别出来。

** 您知道在URI中传递JSON对象是RESTful吗？**

选项清单

/cars?color=black,blue,red;doors=3,5;type=sedan   #most prefered by me
/cars?color:black:blue:red;doors:3:5;type:sedan
/cars?color(black,blue,red);doors(3,5);type(sedan)   #does not look bad at all
/cars?color:(black,blue,red);doors:(3,5);type:sedan   #little difference

可能的功能？

否定搜索字符串（！）
要搜索任何汽车，但不能 搜索黑色和红色：
?color=!black,!red
color:(!black,!red)

加入搜索
搜索红色或蓝色或黑色汽车行驶3门在车库编号1..20或101..103或999，但不是 5 /garage[id=1-20,101-103,999,!5]/cars[color=red,blue,black;doors=3]
然后，您可以构建更复杂的搜索查询。（有关匹配子字符串的想法，请参见CSS3属性匹配。例如，搜索包含“ bar”的用户user*=bar。）

结论

无论如何，这可能是你最重要的部分，因为你可以做你喜欢的毕竟只是记住，REST风格的 URI代表的结构是很容易理解如类目录/directory/file，/collection/node/item，日期/articles/{year}/{month}/{day}..当你忽略任何最后一个细分，您都会立即知道得到什么。

所以..，所有这些字符都可以不编码：

• unreserved：a-zA-Z0-9_.-~
  通常允许同时编码和不允许编码，这两种用法是等效的。
• 特殊字符： $-_.+!*'(),
• 保留：;/?:@=&
  可出于其表示的目的而未经编码使用，否则必须对其进行编码。

• 不安全：<>"#%{}|\^~[]`
  为什么不安全，为什么应该编码：RFC 1738见2.2

  另请参阅RFC 1738＃page-20了解更多字符类。

RFC 3986参见2.2
尽管我之前说过，但这是分隔符的常见区别，这意味着某些“比其他”更重要。

• 通用分度计： :/?#[]@
• 亚微米 !$&'()*+,;=

更多阅读：
层次结构：请参见2.3，请参见1.2.3
url路径参数语法
CSS3属性匹配
IBM：RESTful Web服务-基础知识
注：RFC 1738由RFC 3986更新

尽管在路径中具有参数具有某些优势，但IMO有一些优势。

• URL并非允许搜索查询所需的所有字符。大多数标点符号和Unicode字符都需要URL编码为查询字符串参数。我正在努力解决同样的问题。我想在URL中使用XPath，但并非所有XPath语法都与URI路径兼容。因此，对于简单路径，/cars/doors/driver/lock/combination将适当的位置combination放在驾驶员车门XML文档中的' '元素。但是/car/doors[id='driver' and lock/combination='1234']不是那么友好。

• 根据属性之一过滤资源与指定资源之间是有区别的。

  例如，由于

  /cars/colors 返回所有汽车的所有颜色的列表（返回的资源是颜色对象的集合）

  /cars/colors/red,blue,green 会返回红色，蓝色或绿色的颜色对象列表，而不是汽车的集合。

  要返回汽车，路径是

  /cars?color=red,blue,green 要么 /cars/search?color=red,blue,green

• 路径中的参数更难读取，因为名称/值对与路径的其余部分不是隔离的，路径的其余部分不是名称/值对。

最后的评论。我更喜欢/garages/yyy/cars（总是复数形式）而/garage/yyy/cars不是（也许是原始答案中的错字），因为它避免了更改单数和复数之间的路径。对于带有“ s”的单词，更改不是很糟糕，但是更改/person/yyy/friends为/people/yyy似乎很麻烦。

要扩展Peter的答案-您可以将Search设为一流的资源：

POST    /searches          # create a new search
GET     /searches          # list all searches (admin)
GET     /searches/{id}     # show the results of a previously-run search
DELETE  /searches/{id}     # delete a search (admin)

“搜索”资源将具有颜色，制造模型，保存状态等字段，并且可以XML，JSON或任何其他格式指定。与“汽车和车库”资源一样，您可以基于身份验证来限制对“搜索”的访问。经常执行相同搜索的用户可以将其存储在自己的个人资料中，从而无需重新创建它们。这些URL足够短，以致在许多情况下都可以通过电子邮件轻松地进行交易。这些存储的搜索可以作为自定义RSS提要的基础，等等。

当您将搜索视为资源时，有很多使用搜索的可能性。

这个想法在Railscast中有更详细的解释。

贾斯汀的答案可能是解决方法，尽管在某些应用程序中，将特定搜索本身视为资源可能是有意义的，例如，如果您要支持命名的已保存搜索：

/search/{searchQuery}

要么

/search/{savedSearchName}

我使用两种方法来实现搜索。

1）最简单的情况是查询关联的元素并进行导航。

    /cars?q.garage.id.eq=1

这意味着查询车库ID等于1的汽车。

也可以创建更复杂的搜索：

    /cars?q.garage.street.eq=FirstStreet&q.color.ne=red&offset=300&max=100

FirstStreet中所有车库中不是红色的汽车（第3页，每页100个元素）。

2）复杂查询被视为已创建并可以恢复的常规资源。

    POST /searches  => Create
    GET  /searches/1  => Recover search
    GET  /searches/1?offset=300&max=100  => pagination in search

用于创建搜索的POST正文如下：

    {  
       "$class":"test.Car",
       "$q":{
          "$eq" : { "color" : "red" },
          "garage" : {
             "$ne" : { "street" : "FirstStreet" }
          }
       }
    }

它基于Grails（标准DSL）：http : //grails.org/doc/2.4.3/ref/Domain%20Classes/createCriteria.html

这不是REST。您无法为API内部的资源定义URI。资源导航必须是超文本驱动的。如果您想要漂亮的URI和大量的耦合，但是不要将其称为REST，那是很好的，因为它直接违反了RESTful体系结构的约束。

请参阅REST的发明者的这篇文章。

尽管我喜欢贾斯汀的回答，但我觉得它更准确地代表了过滤器而不是搜索。如果我想了解名称以cam开头的汽车怎么办？

以我的方式看，您可以将其构建为处理特定资源的方式：
/ cars / cam *

或者，您可以将其简单地添加到过滤器中：
/ cars / doors / 4 / name / cam * / colors / red，蓝色，绿色就

我个人而言，我更喜欢后者，但是我绝不是REST的专家（仅在大约2周前才听说过REST ...）

RESTful不建议在URL的/ cars / search中使用动词不是很麻烦。筛选/搜索/分页API的正确方法是通过查询参数。但是，在某些情况下，您必须违反规范。例如，如果要搜索多个资源，则必须使用类似/ search？q = query的内容

您可以浏览http://saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/了解设计RESTful API的最佳做法

另外我还建议：

/cars/search/all{?color,model,year}
/cars/search/by-parameters{?color,model,year}
/cars/search/by-vendor{?vendor}

在这里，Search被视为资源的子Cars资源。

这里有很多适合您的情况的选择。您仍然应该考虑使用POST正文。

查询字符串非常适合您的示例，但是如果您有一些更复杂的内容，例如，任意长项或布尔条件，则可能需要将帖子定义为文档，客户端通过POST发送该文档。

这样可以更灵活地描述搜索，并避免服务器URL长度限制。

我的建议是这样的：

/garages
  Returns list of garages (think JSON array here)
/garages/yyy
  Returns specific garage
/garage/yyy/cars
  Returns list of cars in garage
/garages/cars
  Returns list of all cars in all garages (may not be practical of course)
/cars
  Returns list of all cars
/cars/xxx
  Returns specific car
/cars/colors
  Returns lists of all posible colors for cars
/cars/colors/red,blue,green
  Returns list of cars of the specific colors (yes commas are allowed :) )

编辑：

/cars/colors/red,blue,green/doors/2
  Returns list of all red,blue, and green cars with 2 doors.
/cars/type/hatchback,coupe/colors/red,blue,green/
  Same idea as the above but a lil more intuitive.
/cars/colors/red,blue,green/doors/two-door,four-door
  All cars that are red, blue, green and have either two or four doors.

希望能给你这个主意。本质上，您的Rest API应该易于发现，并使您能够浏览数据。使用URL而不使用查询字符串的另一个优点是，您可以利用Web服务器上存在的用于HTTP流量的本机缓存机制。

这是指向描述REST中查询字符串的弊端的页面的链接：http ://web.archive.org/web/20070815111413/http://rest.blueoxen.net/cgi-bin/wiki.pl? QueryStringsConsideredHarmful

我使用Google的缓存是因为正常页面对我不起作用，这里的链接也是如此：http : //rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful