RESTful API 设计最佳实践

Question

我正在为我的项目编写API层，但在尝试解决以下场景的设计问题时遇到了困难：

1. 所有用户都有一份书籍清单
2. 每个清单可以通过ID访问
3. 用户可以自由添加和删除书籍

目前，我不确定最好的方法是哪种：

1) PUT - /api/list/{listID}/{bookID} - Add book to specified list
   DELETE - /api/list/{listID}/{bookID} - Remove book from specified list
2) PUT - /api/list/{listID} - Send XML data to server that contains bookID and action
   <list_payload>
       <action>{delete|add}</action>
       <bookID>{bookID}</bookID>
   </list_payload>

任何想法和见解都将不胜感激。

- jfrey

Answer 1

我这样想

1)POST - /api/lists/{listID}/books - Add book to specified list
2)PUT - /api/lists/{listID}/books/{bookID} - Edit book from a specified list
3)DELETE - /api/lists/{listID}/books/{bookID} - delete

对于List

POST - /api/lists Add list
PUT - /api/lists/{listID} Edit list
DELETE /api/lists/{listID} Delete list

- Dnyan Waychal

---

是的。重要的是，所有不幂等的操作都需要通过POST进行；PUT必须是幂等的（即，如果浏览器静默地重复它，那不应该是一个坏事）。 - Donal Fellows

那么在第二种情况下的PUT方法中，您是否会将“编辑操作”（即添加或删除）作为URL参数传递？ - jfrey

你可以在saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/了解一些REST API的最佳实践。 - java_geek

Answer 2

REST没有限制，因为它更像是通过HTTP来解决问题，而不是像SOAP这样有强标准的硬性web服务协议。

也就是说，两种选择都可以有效，但是为了简单起见，我认为您应该选择第一种选项。

- Martin Revert

Answer 3

我认为这是一个非常好的、清晰的指南，可以帮助理解如何设计正确的REST服务。它不仅涵盖了这个问题，还提供了更多关于设计过程的线索。 你可以观看：https://www.youtube.com/watch?v=hdSrT4yjS1g 或者你可以快速查看：http://www.slideshare.net/stormpath/rest-jsonapis

- Kunthar

Answer 4

这里有一个实验性的JSon服务链接，包含Web和Android的源代码下载链接： developersfound.com/RESTExperiment/

我在业余时间做了很多有关REST的实验性代码。最近我用过并尝试了许多框架，最终意识到简单的HTTP JSON是最有效的。 许多人认为REST的优点在于无状态性，但HTTP也是无状态的。HTTP具有状态，如果需要的话，可以使用连接状态或会话状态。它还更加安全。 然而，如果你坚持使用REST，试着找一个不使用自定义路由（依赖正则表达式）的路由引擎框架，因为这会给服务器带来很大的负担。非正则表达式路由对设计和开发服务的方式有些限制，但如果你看重快速且没有瓶颈的服务器，那么这将是值得的。另一种减少瓶颈的好方法是使用存储过程而不是透传查询。对于那些不知道什么是透传查询的人来说，它正好与使用存储过程相反，当开发人员在服务器上动态生成一个SQL字符串并将其传递给数据库时，就是透传查询。存储过程消除了瓶颈，因为透传查询会导致服务器每次受到攻击时都要动态生成SQL。使用存储过程只需直接从请求中传递参数到数据库即可。此外，存储过程是编译的，这意味着即使数据库也不必动态生成SQL。1992年SQL 92标准出台后，透传查询就成为了遗留技术。我上面提供的链接实际上是实验性代码，但你会发现这篇博客非常有见地。

- user2288580

Answer 5

正如@MartinRevert所指出的，REST API设计实际上没有任何限制，除非你自己设定。

对于我自己而言，我建议专注于可测试性和UI开发人员的简单性，而不是利用HTTP协议的所有功能。最终，他们是你的客户，如果他们的JavaScript框架没有遵循所有HTTP资源约定（Angular在早期版本中没有遵循201 Created重定向）

GET用于检索数据。主要是因为它可以被缓存。这将返回适当内容类型的数据。

POST将修改数据或接受复杂的搜索查询。在我的合同中，这将始终返回JSON对象。

通过将事物保持为仅POST，您可以创建一个简单的表单，而无需执行XHR操作来进行一些功能测试。

我在这里写了一个更详细的答案 http://www.trajano.net/2014/07/rest-api-contract/

- Archimedes Trajano

Answer 6

我会将第一个例子解释为您正在更新列表中存在的书籍。这意味着，该书已经有了自己的设置数据，但在列表中它有更多的属性，您可以通过{listID}/books/{bookID} URL来更新它们。

如果您想要更新列表的内容（即添加或删除书籍），那么在lists/{listID} URL上调用PUT对我来说是最有意义的。

-丹

- Dan