继 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，它们都是很好的设计实践。
暂无签名
中国开发者画像洞察研究报告 2024
分析开发者的行为模式、工作价值、职业发展等内容，帮助整个行业生态更深入地理解开发者，为他们提供更精准...
评论