GOTO Berlin: Web API设计原则

在邮件列表和讨论区中有很多与RESTWeb API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver WolfGOTO 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

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏JavaQ

不得不推荐的开发利器

子曰:“工欲善其事,必先利其器“,事先把工具准备好,可以起到事半功倍的效果,本篇将介绍开发过程中经常使用到的开发工具们。

1872
来自专栏竹清助手

如何理解一个高度抽象化的架构风格本质

REST本身是一个高度抽象化的架构风格,因而总是很难对它有一个比较深入且印象深刻的理解。写这篇文章的目的,是自己对学习REST的一个总结,也希望可以通过这篇文章...

1813
来自专栏JavaQ

解决程序报错的套路

当程序运行发生错误时,你需要学会使用常用套路去分析并解决这些问题,下面介绍一些常用的套路。

883
来自专栏EAWorld

微服务转型,雪崩效应是绕不过的一道坎

记得在三年前公司因为业务发展需要,就曾经将单体应用迁移到分布式框架上来。当时就遇到了这样一个问题:系统仅有一个控制单元,它会调用多个运算单元,如果某个运算单元(...

52112
来自专栏SDNLAB

漫谈虚拟路由方案

前言——关于虚拟路由 SDN,抑或是OpenFlow,能否为路由市场开辟一个新的时代?以OpenvSwitch为代表的开源软件交换机,已经推动SDN界发展了一段...

4205
来自专栏Android群英传

Android中的睡与不睡

1002
来自专栏美团技术团队

美团点评智能支付核心交易系统的可用性实践

2367
来自专栏cloudskyme

模块化服务规范——OSGI

什么是OSGI OSGi(Open Service Gateway Initiative)有双重含义。一方面它指OSGi Alliance组织;另一方面指该组织...

4583
来自专栏腾讯移动品质中心TMQ的专栏

论Android适配踩到的坑

说起Android适配,恐怕是每一个Android开发/测试工程师心里的痛,且不论Android设备品牌众多、分辨率各异等痛点,单论Android版本的繁多也会...

3508
来自专栏开源项目

那些优秀的网络爬虫工具介绍,最后亮了!| 码云周刊第 16 期

技术干货 1、SpringMVC 执行流程及源码解析 2、使用 Vue2 和 Yii2 进行前后端分离开发 3、 SSM (十一) 基于 dubbo 的分布式架...

57310

扫码关注云+社区