我在想如何让RESTFul API更具有意图。我在各种博客上看到的常见模式是传统的REST API导致的结果
禁止球员 - > POST /players.
但我可以改用更具意图的界面,我可以使用
禁止球员 - > POST /players/{ playerid }/banPlayer
我觉得第二个更有意图揭示。
我从团队得到的共同反对意见是第二个不符合启动REST风格。
目前我也无法摆脱RESTful API。
我想听听你对此的看法。
使用Restful API设计,有两种思路可以解释如何将actions
应用于资源。
POST /players/{id}/ban
注意:只需使用ban
- 我们已经知道资源是一个玩家,它在基础Uri中。POST /players/{id}
请求机构:
{ 'action': 'ban' }
您可以选择任何一种方式 - 无论您喜欢哪种方式,都会对两者进行大量讨论,但最终两者都是正确的。
注意:
我在这里假设禁止播放器不仅仅是更新它的一部分,而是与播放器相关的系统动作(或状态转换)。否则,如果它只是对播放器资源的更新,则应根据需要使用PATCH或PUT进行处理。
一些讨论供参考:
如果你做一些谷歌搜索,还有更多......
您提到的两个示例都不是正确的REST api。
实现这一点的更正确的方法是,你有一个'玩家'资源。该播放器资源可能具有属性banned
,这是一个布尔值。
要将banned
属性设置为true,您可以发出如下请求:
PUT /players/1234
并让请求正文包含禁用属性的新值。
根据REST API方法,您需要在URI中使用您的实体,因此,由于banPlayer
不是实体,因此您无法使用它。我建议用PUT方法更新你的记录。 Here你可以阅读更多有关规则的内容。实际上,关于URI的第一部分就是关于你的情况。
长话短说:它不应该是强制性的意图揭示,但如果你想在这个API看起来如何添加一些DDD然后它没有什么阻止你这样做
根据HATEOAS对RESTful Web API的约束(这种约束是REST的“统一接口”功能的一个重要部分,如Roy Fielding的博士论文中所定义),API的软件客户端不应该关心URL。应该在响应中包含每个可能的和允许的操作,以及相应的link relation和URI。通过这种方式,您只需要对链接关系进行硬编码。
但是,这种约束并不会阻止您为尝试理解整体架构的Human客户端提供更多意图。我建议您选择此路径,因为人类用户至少与他们编写的软件一样重要。
罗伊菲尔丁在his blog post上写到了这一点。
我从团队得到的共同反对意见是第二个不符合启动REST风格。
答案很简单:API的一致性有价值,无论是否REST。所以“这不是我们在这里做的事情”将打败“但REST说”。
API中URI的拼写很像代码中方法名称的拼写。不同风格有很多不同的论点,但“本地约定”本身就是一个强有力的论据。
那就是说 - REST不关心你用于标识符的拼写。
这就是Fielding had to say in 2008
REST API应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型,或者为现有标准媒体类型定义扩展关系名称和/或启用超文本的标记。在媒体类型的处理规则的范围内(并且在大多数情况下,已经由现有媒体类型定义)应该完全定义用于描述在感兴趣的URI上使用什么方法的任何努力。 [失败在这里意味着带外信息驱动交互而不是超文本。]
带内将包括资源表示中的URI - 将其放入HTML文档中的表单描述中。带外正在记录URI,并希望人们用它来做正确的事情。
注意:人类可读的URI或记录应该使用的URI没有任何问题。但请注意,即使编写浏览器的人没有阅读stack overflow's API documentation(即REST),您也可以将问题发布到stackoverflow。
既然你要求RESTful方式不是最好的方式,这就是我的想法。
您的RESTful URI选项包括:
/players
/players/{ playerid }/banPlayer
/player-banning
/entities?action=ban_player&method=PUT
/banana
RESTful方法是纯粹通过超文本公开下一个可用状态的知识。要执行REST,必须使用超文本作为应用程序状态引擎(HATEOAS)。依赖客户端对URI的了解取决于带外知识,这与REST是对立的。
您的资源不需要直接映射到业务对象。如果您选择,您可以将用户意图本身表示为资源,例如被禁止的玩家活动资源。你可以通过一些关于禁止哪个玩家的信息来发布它,随后的GET将提供有关该事件的信息。
哦,只是因为REST不关心你的URI是什么,并不意味着你不应该。你只需要使用不同的标准来决定什么是最好的。