BT

如何利用碎片时间提升技术认知与能力? 点击获取答案

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

| 作者 Boris Lublinsky 关注 1 他的粉丝 ,译者 马国耀 关注 1 他的粉丝 发布于 2011年6月13日. 估计阅读时间: 4 分钟 | QCon上海2018 关注大数据平台技术选型、搭建、系统迁移和优化的经验。

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

评价本文

专业度
风格

您好,朋友!

您需要 注册一个InfoQ账号 或者 才能进行评论。在您完成注册后还需要进行一些设置。

获得来自InfoQ的更多体验。

告诉我们您的想法

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我
社区评论

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

讨论

登陆InfoQ,与你最关心的话题互动。


找回密码....

Follow

关注你最喜爱的话题和作者

快速浏览网站内你所感兴趣话题的精选内容。

Like

内容自由定制

选择想要阅读的主题和喜爱的作者定制自己的新闻源。

Notifications

获取更新

设置通知机制以获取内容更新对您而言是否重要

BT