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