本文探讨了REST API设计中的最佳实践与常见误区，包括如何使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
扫一扫
108
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
