用于搜索的RESTful URL设计

可能的功能？

否定搜索字符串(!)
搜索任何汽车,但不 搜索黑色和红色:
?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}..当你忽略任何最后一段,你立即知道你得到了什么.

所以..,所有这些字符都是允许未编码的:

毫无保留: a-zA-Z0-9_.-~

版权所有: ;/?:@=&$-_.+!*'(),

不安全*: <>"#%{}|\^~[]`

*为什么不安全以及为什么要编码:RFC 1738见2.2

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看起来很麻烦.

为了扩展彼得的答案 - 你可以使搜索成为一流的资源:

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或任何其他格式指定.与Car和Garage资源一样,您可以根据身份验证限制对搜索的访问.经常运行相同搜索的用户可以将其存储在其配置文件中,以便不需要重新创建它们.这些网址足够短,在很多情况下,它们可以通过电子邮件轻松交易.这些存储的搜索可以是自定义RSS源的基础,依此类推.

当您将搜索视为资源时,可以使用搜索.

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

Justin的答案可能是要走的路,尽管在某些应用程序中将特定搜索本身视为资源可能是有意义的,例如,如果您想支持已命名的已保存搜索:

/search/{searchQuery}

要么

/search/{savedSearchName}

这不是REST.您无法为API中的资源定义URI.资源导航必须是超文本驱动的.如果你想要漂亮的URI和大量的耦合,那就好了,但是不要把它称为REST,因为它直接违反了RESTful架构的约束.

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

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

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