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

继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