用于搜索的RESTful URL设计

Question

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

设置:我有两个模型,汽车和车库,汽车可以在车库.所以我的网址看起来像:

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

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

汽车可以独立存在(因此/汽车),也可以存在于车库中.例如,在给定车库中代表所有车辆的正确方法是什么？就像是:

/garage/yyy/cars     ?

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

什么是代表搜索具有某些属性的汽车的正确方法？说:给我看看所有带4扇门的蓝色轿车:

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

或者它应该是/汽车而不是？

使用"搜索"似乎不合适 - 什么是更好的方式/术语？应该只是:

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

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

简而言之,我正在寻找跨模型REST网址设计和搜索的指导.

[更新]我喜欢贾斯汀的答案,但他没有涉及多字段搜索案例:

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

或类似的东西.我们怎么样

/cars/color/blue

到多场案件？

Answer 1

对于搜索,请使用查询字符串.这完全是RESTful:

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

常规查询字符串的一个优点是它们是标准的并且被广泛理解,并且它们可以从form-get生成.

Answer 2

在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.

搜索

搜索查询是可以的,只有你的偏好,应该考虑什么.加入搜索时会出现有趣的部分(见下文).

/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}..当你忽略任何最后一段,你立即知道你得到了什么.

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

• 毫无保留: 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更新

Answer 3

虽然在路径中具有参数具有一些优点,但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看起来很麻烦.

Answer 4

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

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中有更详细的解释.

Answer 5

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

/search/{searchQuery}

要么

/search/{savedSearchName}

Answer 6

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

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

Answer 7

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

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