REST API 的好的、坏的及难堪的实践

  • Boris Lublinsky
  • 马国耀

2011 年 6 月 12 日

话题:SOAREST架构

InfoQ 上 REST 相关的一番有趣讨论之后,George Reese 最近发表了一篇颇有意思的博文——REST API 的好,坏和难看之处,文中谈到了在 REST API 开发过程中许多的该做与不该做。

Reese 强调的创建 REST API 的较好的实践有:

  • API 模型应该与数据的消费行为映射,而不要与数据模型或对象模型映射。
    API 调用的数据看上去不应该像高度规范化的数据库表的表象;而应该以对 API 的消费者有意义的模型呈现。

    该提法类似于这一 SOA 原则:将消息模型与底层数据访问模型分离。

  • 语义丰富的错误消息很有用。创建 API 时,有必要
    思考人们在学习使用该 API 过程中可能会犯的各种错误。

    对于做错的事情返回一个详细解释。此演示中给出了一些这类消息的不错的示例。

  • 完备的文档将减少寻求外部帮助的需要。
    完备的 API 文档技能帮助人们理解简单的快速入门的例子,又能帮助人们完成一些复杂的事情,如通过 API 完成高级任务。
  • 使用恰当的安全 API。比如,Reese 提到的常常与 REST 一起使用的 OAuth 认证,在 API 向浏览器提供内容的场景中它能很好地工作,但对于系统到系统的整合它却不适用。更多有关 REST API 安全的讨论可从“RESTful API 认证模式”找到。
  • REST 好,SOA 不好。Reese 说,
    当目标客户使用多种不同的编程语言时,实施和支持 SOA 的难度极大。

    他进一步断言,

    JSON 好,XML 不好。

    而“支持 JSON 的 REST 比强制 XML 的 SOAP 更好”这一观点遭到 Gerald Loeffler 的直接批判,他在 InfoQ 新闻"REST 在企业中使用得成功吗?"的回复中说到:

    ……若不从纯技术角度去比较这些技术,我们就会丢失任何技术都需要的那种严谨……当人们沉浸在自己看到的世界里(你可以称之为理想主义者;比如 WS-* 或 REST;或者静态类型或动态类型),他们就不可避免地认为他们看到的就是真实——因为一切都如此的明显而真实。但事实并非如此:这只是认知和推理的一家之言而已(该认知包含特定的特征和属性——正因为这样,我们仍然需要纯技术的论战)。不幸的是,在软件开发中,人们对自己观点的支持常常以反对者这样的冒犯而告终:“他们根本不懂”。

Reese 列出的较差(和难堪)的实践有:

  • 流量控制是极难处理的事情。
    如果你要使用流量控制……那么你就要实现一些非常智能的手段:a) 它能识别出合法的流量,如测试流和常规的轮询。此外,b) 减低误判所造成的负面影响。要避免基于无端猜测去限制流量,要咨询客户哪些人可能会受影响。
  • 罗嗦的 API 最可恶。根据 Reese,罗嗦的 API 就是那种要求使用者执行多次调用才能完成一次普通操作的 API。当然,怎样算是罗嗦的 API 要取决于人们一般对 API 的期望。
  • 在响应中返回 HTML。Reese 建议,即便服务响应不能与 API 服务端交互,它仍然应该是一个有效的 JSON 或 XML。
    只要 API 使用者看到 HTML,就意味着你做了一件非常,非常错误的事情。
  • 处理 500 以上的错误带来的副作用是噩梦。API 应总是能保证产生 500 以上错误的那些调用的幂等性——回滚产生错误的过程中作过的任何更改。

Reese 的博客为读者带来了一组很好的 REST API 实施的最佳实践,文中既描述了哪些该做和哪些不该做,还描述了原因——藏在好与坏背后的理由。这些最佳实践并非 REST 所特有的——它们不关乎REST 设计定义资源选择正确的参数传递机制——不论对于哪种 API,它们都是很好的设计实践。


查看英文原文:The Good, the Bad, and the Ugly of REST APIs
SOAREST架构