REST URI和对象的操作,可以对其进行评论,标记,评级等

我正在为我的公司研究一个Web API,它开始看起来像我们可能实现一个RESTful的.我现在已经阅读了几本关于此的书(O'Reilly的"RESTful Web服务"似乎最有用),并为可以评论,标记和评级的对象提出了以下一组URI和操作. .

对象是什么并不重要,因为这种情况适用于网络上的许多事情,但为了争论,我们可以说这是一部电影.

其中一些似乎非常自然,但其他人似乎有点强迫(特别是评级和标记)所以有人对如何改进这些有任何建议吗？我将列出它们与URI,然后支持动词,以及我建议他们会做什么.

/movies

GET =列出电影

/movies/5

GET =获取电影5

/movies/5/comments

GET =列出对电影5的评论

POST =在电影5上创建新评论

/movies/5/comments/8

GET =在电影5上获得评论8

POST =回复关于电影5的评论8

PUT =更新电影5的评论8

/movies/5/comments/8/flag

GET =检查电影是否标记为不合适(如果不是,则为404)

PUT =将电影标记为不合适

/movies/5/rating

GET =获取电影的评级

POST =将电影的用户评分添加到总评分中

编辑:我的意图是电影对象将其评级作为属性,所以我真的不希望在这里使用GET方法.URI确实存在,因此评级可以是可以使用POST动词更新的单个资源.我不确定这是否是最佳方式,但我想不出更好的方法

/movies/5/tags/tagname

GET =检查电影是否标记有标记名(如果不标记,则为404;但如果标记有标记名称,则应通过重定向到类似/tags/tagname？来返回实际标记资源)

PUT = 为电影添加标记标记名,/tags/tagname如果需要,创建标记资源

DELETE = 从影片中删除标记标记名,tags/tagname如果删除后没有标记任何内容,则删除标记资源

请注意,这些不是整个URI,例如列出电影的URI将支持过滤,分页和排序.为此,我计划的事情如下:

/movies/action;90s/rating,desc/20-40

哪里:

action; 90s是一个以分号分隔的过滤条件集

等级,desc是排序顺序和方向

20-40是要获得的项目索引的范围

关于这个API方案的任何评论呢？

编辑#1

这篇文章现在变得很长!在阅读了一些答案和评论之后,这是我计划制作的以上内容的变化:

标签将作为一个组而不是单独处理,因此它们将位于:

/movies/5/tags

GET = List标签

POST =指定标签和现有标签的联合

PUT =用指定的标签替换任何当前标签

DELETE =删除所有标签

我仍然不确定如何处理标记评论.一个选项是,注释对象将包含其父级,而不是POST到回复它的注释,因此它可以被POST到一般URI,即

/movie/5/comment

POST =创建新评论(可能是对评论的回复)

然后我可以使用POST来评论标记它.但这仍然感觉不太对劲.

/movie/5/comment/8

POST =标记评论

你所拥有的大多数看起来都很好.我看到的只有几件奇怪的事情.当我将我的网址放在一起时,我会尝试遵循这四个原则.

剥洋葱

如果你让REST中的R真的是一个资源,那么资源URL应该能够被剥离并且仍然有意义.如果没有意义,您应该重新考虑如何组织资源.因此,在下面的情况中,每个都是有道理的.我要么看一个特定的项目,要么是一组项目.

/movies/horror/10/
/movies/horror/
/movies/

以下对我来说似乎很有趣,因为flag它不是一种资源,它是一种属性movie.

/movies/5/comments/8/flag -> Funny
/movies/5/comments/8/     -> Gives me all properties of comment including flag

定义视图

URL的最后一个描述如何显示资源.URL /movies/horror/ 告诉我,我将收集一些恐怖电影.但是我可能有不同的方式来显示该集合.

/movies/horror/simple
/movies/horror/expanded

简单的视图可能只是标题和图像.展开的视图将提供更多信息,如描述,概要和评级.

助手

在资源受限并找到正确的视图后,查询字符串参数用于帮助UI处理小东西.我使用的最常见的查询字符串参数是

p => Page
n => number of items to display
sortby => field to sort by
asc => sort ascending

所以我最终可能会得到一个像这样的网址

/movies/horror/default?p=12&n=50&sortby=name

这将给我movies带有默认视图的限制恐怖电影列表; 从第12页开始,每页有50部电影,电影按名称排序.

操作

最后需要的是你对资源的行动.该操作是基于集合或基于项目.

/movies/horror/
GET -> Get resources as a list
POST -> Create, Update

/movies/horror/10/
GET -> Get resource as item
POST -> Update

我希望这有帮助.