在 Web 服务中应该将信息原子化到什么级别？

Question

我正在实现一个 REST Web 服务，我想知道是否有任何关于如何将服务公开的信息原子化的约定。到目前为止，我一直无法找到令人满意的解决方案，所以现在我向互联网上最伟大的人提问：P

例如，假设我想实现一个 API 来访问某种库注册表，所以我们有一个路径为 /books 的资源。例如，通过阅读/books/123，我们将获得以下 XML 数据：

<?xml version="1.0" encoding="utf-8"?>
<book>
    <title>Visit Catalonia</title>
    <author>J. Hans</author>
    <year>2000</year>
</book>

假设作者信息有误，我想通过 Web 服务的 API 更改它。我提出了两种可能的选择，每种都有优点和缺点：

选项 1： 使用以下数据向/books/123 发出 HTTP PUT 方法：

<?xml version="1.0" encoding="utf-8"?>
<book>
    <author>G. Robinson</author>        
</book>

优点：

• 只需要实现 1 个资源处理程序：/books/BOOKID
• 我们可以修改数据中定义的 XML 标记的尽可能多的信息（例如：添加上面的代码，我们也会更新图书的年份）。

缺点：

• GET 方法总是返回关于一本书的所有数据；我们不能只访问一条信息。在此示例中，获取所有数据不是问题，但如果 /book/123 也有一个带有图书内容本身的标签以便在线阅读呢？

选项 2： 向/books/123/author发出HTTP PUT方法发送数据：

<?xml version="1.0" encoding="utf-8"?>
<author>G. Robinson</author>

优点：

• 可以以任意深度访问信息：API 客户端只需下载他/她需要的信息。

缺点：

• 我们无法通过单个 HTTP 请求获取或修改多条信息。
• 实施起来很困难：子资源与信息字段一样多。

因此，总而言之，我的问题是是否有任何普遍接受的约定可以在 Web 服务中公开信息。当然，在管理少量数据的简单 Web 服务中，这不是问题，但如果我们公开真实世界的数据库怎么办？

非常感谢您。

Answer 1

远程接口（如 Web 服务）通常是粗粒度的。这样可以最大限度地减少网络开销。

使用数据向/books/123 发出 HTTP PUT

<?xml version="1.0" encoding="utf-8"?>
<book>
    <author>G. Robinson</author>        
</book>

在我看来，这本书不再有<title> 和<year>。您 PUT 到 /books/123 的数据应包括所有关于图书的相关信息，即使是未更改的信息。

向/books/123/author 发出带有数据的HTTP PUT

<?xml version="1.0" encoding="utf-8"?>
<author>G. Robinson</author>

是您期望从本地界面而不是远程界面获得的那种精细控制。如果使用粗粒度界面一次更新整本书数据的成本过高（例如，如果书籍数据还包含书籍的全文并且您经常只需要更新单个属性），则在粗粒度界面之外使用此接口.

Answer 2

我相信您可以两者兼得，具体取决于您要支持的客户需求/情况：

• GET/POST /books/123 ：您获取并发布（创建/更新）完整的图书属性
• GET/POST /books/123/author ：您获取并发布（创建/更新）本书的作者

您没有理由不能同时使用这两个选项。客户可以根据他们所处的情况遵循其中一个或另一个...在创建新书条目或更新整个条目时，选项 1 似乎更合适...而如果您在客户端 UI 中允许更新，则选项 2一次“一个财产”。因此，这可能在很大程度上取决于您想要支持的客户“意图”/情况......您在设计时应该考虑到这一点。

我刚刚阅读了一篇关于 InfoQ 的精彩文章，其中涉及到了其中的一些要点（以及其他内容）。看看“不要暴露你的领域模型”和“根据意图设计你的 API”点 - http://www.infoq.com/news/2013/10/gotober-do-dont-webapi。