GOTO Berlin: Web API 设计原则

在邮件列表和讨论区中有很多与 REST 和 Web API 相关的讨论，下面仅是我个人对这些问题的一些见解，并没有绝对的真理，InnoQ 的首席顾问 Oliver Wolf 在 GOTO Berlin 大会上开始自己的演讲“Web API 设计原则”时如是说。

不要考虑端点。 SOAP 有一个单独入口点的外观。相比之下 Web 有很多入口点，它们建立在关系上，彼此之间相互连接，并且以超媒体作为关键要素。为了不让你的 API 成为一个只有一种接入方式的黑洞，你应该使用超媒体控制按照对听众有意义的表现方式去链接你的资源。

** 不要在API中暴露领域模型。** 在很多模型中存在的一个问题便是它们仅包含数据，缺乏所有形式的行为，也就是所谓的贫血模型（anaemic model）。如果你暴露这样一个模型，那么最终将会成为 CRUD （创建、读取、更新和删除）和资源。这并不一定是一件坏事，有时你所需要的所有内容便是一个纯粹的 CRUD API。否则暴露一个 CRUD 模型的问题便是，使用这样一个 API 的客户端需要了解很多知识，清楚它能够对哪些资源执行什么操作，按照什么样的顺序执行等等这些内容。大量的逻辑需要编码在客户端中，使得客户端和服务器之间变得紧耦合。

** 目的明确之后再设计API。** 想想你的客户端想要做什么，如何做。有时这需要在清晰度和灵活性之间权衡，你需要多么简单清晰的 API，需要什么程度的灵活性。一种灵活但是也更加迫切的获取最有利可图的客户的方式是：

 
GET /customers?sortBy=grossmargin&order=descending

相比之下，下面是一种声明意味更浓的暴露意图的方式，但是也缺乏灵活性：

 
GET /most_profitable_customers

Oliver 提到这里需要注意的一点是，考虑一下客户端需要使用你的 API 做什么，它的意图应该是什么，并尽量让它完美契合这些需要。

** 不要过度使用GET和POST。** 这基本上意味着你不应该按照错误的方式使用它们，也不能违反 HTTP 规范。例如，你不应该使用 GET 或者 POST 删除资源。每个 HTTP 动词的产生都有各自的原因，它们之间是互补的，通过拥抱规范你得到的将会更多。使用动词传达目的，客户端想要做什么，它们期望从服务器得到哪些行为。

** 不要将错误码的选择限制为200和500。** 使用完整范围的错误码，有 160 个错误码供你选择，所以几乎每一种类型的错误都有一个对应的错误码。使用正确的错误码是客户端能够合理处理错误的关键。一个常见的问题是，尽管发生了一个错误但是服务器依然返回 200，OK。在这种事情发生时假装所有事情运行良好显然不是一个很好的想法。

不要忽略缓存。 无论涉及到什么都会有缓存，它是 Web 的一个非常重要的部分。如果你不想使用缓存，那么通过添加合适的缓存头明确地关闭它。
一种比较好的控制缓存的方式是使用验证器，最好是 Etags。它们允许服务器端操作任意的数据，一个 Etag 仅仅是服务器生成并传入缓存的一个值，然后缓存会将其传回以询问服务器是否有更新的资源。

不需要版本。通常情况下，当资源发生变化的时候实际上它仅仅是展示发生了改变，而它依然是那个资源，应该使用同一个 URL，因此避免将 URL 版本化。相反的，应该有一个新版本的媒体类型，例如通过下面的方式添加版本 v2：

 
Content-Type=application/vnd.company.v2+xml

不要对内容协商使用扩展。协商一种表现格式的正确方法是在消息头中使用 Accept 和 Content-Type。

2013 年的 GOTO Berlin 大会是 GOTO 大会首次在 Berlin 举行，本次大会有超过 400 位参会者和大约 80 位讲师。

查看英文原文： GOTO Berlin: DO’s and DON’Ts in a Web API