低代码到底是不是行业毒瘤?一线大厂怎么做的?戳此了解>>> 了解详情
写点什么

非 RESTful 的微软 REST API 指南

2016 年 7 月 27 日

微软发布了创建“RESTful” API 的指南。Roy Fielding 将这些与 REST 没有多大关系的 API 称为 HTTP API。

许多组织都发布了创建面向 Web 的 HTTP API 的建议,甚至是白宫都发布了一份标准——“白宫 Web API 标准”。近日,微软公开了他们的“微软 REST API 指南 2.3 ”,这是一份全面而成熟的规范。该规范被制定出来,主要是供 Azure 团队在构建云服务时使用。

下面总结了微软 API 指南的一些关键点,感兴趣地读者可以阅读完整的规范。

  • 为了便于 API 的应用,URL 应该是人类可读和可构造的,而不必借助客户端库。
  • 应支持以下 HTTP 谓词:GET、PUT、DELETE、POST、HEAD、PATCH、OPTIONS。不是所有的资源都应该支持所有的谓词。
  • GET、PUT、DELETE 和 HEAD 应该是幂等的。
  • 自定义头信息不是必须的。
  • 客户端应该不需要在 URL 中传递个人身份信息参数,因为它们可能会暴露在日志文件中。参数应该通过头信息传递。
  • 数据应该以流行的格式提供。
  • 默认数据编码是 JSON。
  • “基本型数值必须遵循 RFC4627 标准序列化成 JSON。”
  • 使用 API 的开发人员应该能够使用喜欢的语言和平台。
  • 即使是简单的 HTTP 工具,如 curl,也应该能够访问服务。
  • API 应该支持显式版本。
  • 服务应该保持稳定,如果可能,就不要引入破坏性修改,但如果必要,它们也应该允许这样做,通过增加版本号标识出来。
  • 版本应该使用一种 Major.Minor 方案。
  • 服务可以通过 Web 钩子(HTTP 回调)实现推送通知。

该指南提供了一个例子,说明了什么样的 URL 是结构良好的 URL:

复制代码
https://api.contoso.com/v1.0/people/jdoe@contoso.com/inbox

而另外一个例子说明了什么样的 URL 是应该避免的:

复制代码
https://api.contoso.com/EWS/OData/Users('jdoe@microsoft.com')/Folders('…[very long identifier]…=')

Roy Fielding 是 REST 及 HTTP/1.1 的作者,同时也是 Apache 基金会的联合创始人。在微软发布这份 REST API 指南之后不久,他就表达了对这份规范的不满:“即使是我最糟糕的REST 描述也比 [微软 /aip 指南] 提供的总结或参考要好很多。”InfoQ 联系了 Fielding,更详细地了解他为什么对这份规范不满意。以下是他的完整回复:

我认为,像微软这样的公司决定将部分内部文档和开发指南发布到公共论坛,尤其是像 GitHub 这样的开源协作空间,是很好的。对于公共对话的这种开放性将极大地改善我们这个行业的工作方式。

对于这份指南,我不满意的是,这份指南明明是总结了如何在微软的生态系统中开发合理的 HTTP API,但却冠以 REST 和 RESTful API 的标签。REST 不等于 HTTP,这是显而易见的,粗略地读下任何有关 REST 的资料就可以知道。这份指南明显不是基于 REST 的,他们甚至没有设法参考我的工作(除了已经被 RFC7231 废除的 RFC2616 的部分内容)。对于以前深入 Web Services 世界的人们,这是一个常见的错误:将 REST 描述成 SOAP/RPC 接口的某种 HTTP 版本。

不管那种错误在实际中多么常见,它都不能自称是 REST。REST 架构风格的大部分属性都源于对其所有约束的坚持,而不只是那些与过去已失败的工具类似的约束。如果那些想要使用 HTTP 构建 RPC 接口的人们,将它们的接口称为 HTTP API,那么我没有任何意见。它们不是 REST 的。它们不属于 Web。那并不是说,它们不能被诚实地描述,并实现为 HTTP 服务。要这样理解它们,讨论它们的实现指南,而又不觉得需要遵从错误的说法,这是值得的。

许多 Web 服务提供商都使用了 HTTP API,并且运用得非常成功。大部分云计算都是基于这样的 API。不知道为什么这么多人坚持把它们的服务称为“RESTful”,而它们并不是。关于这个问题,我们建议那些有兴趣了解更多信息的读者阅读下列 InfoQ 文章:《为什么有些Web API 不是RESTful 的?针对这些API 我们能做些什么?》、《与Roy Fielding 谈论版本化、超媒体以及REST 》。

查看英文原文 Microsoft REST API Guidelines Are Not RESTful

2016 年 7 月 27 日 19:005615
用户头像

发布了 1008 篇内容, 共 315.1 次阅读, 收获喜欢 284 次。

关注

评论

发布
暂无评论
发现更多内容

MySQL分区表最佳实践

Simon

MySQL 数据库

实现一致性hash算法

LEAF

Week05总结

熊威

架构师训练营 - 命题作业 第 5 周

铁血杰克

架构师训练营第五章总结

吴吴

学习总结 -- Week 5

吴炳华

极客大学架构师训练营

第五周作业

刘卓

一致性 hash 算法

changtai

极客大学架构师训练营

计算机操作系统基础(十五)---使用fork系统调用创建进程

书旅

php laravel 操作系统 进程 线程’

第5周总结

娄江国

极客大学架构师训练营

一致性 Hash Java 实现

陈皮

架构师训练营 - 学习总结 - 第五讲

吕浩

Hash 一致性虚拟节点算法

李锦

基于领域驱动设计的业务中台架构设计

Winfield

中台 业务中台 领域驱动设计 DDD

架构师训练营第5周总结

时来运转

阿里巴巴、百度、美团都在用的 Spring Cloud 微服务架构

java通天架构哪吒

Spring Cloud SpringCloud

「架构师训练营」Week5作业

Frank Zeng

一致性哈希算法

dony.zhang

一致性哈希

week5 home work

东哥

一致性哈希

第五周学习总结

刘卓

「架构师训练营」第五周作业

旭东(Frank)

算法 极客大学架构师训练营 哈希 一致性哈希

架构感悟5-算法之美

旭东(Frank)

架构 算法 感悟 极客大学架构师训练营

架构师训练营第五章作业

吴吴

架构师训练营Week 05 学习总结

Frank Zeng

第五周学习总结

冯凯

架构师训练营第5周作业

时来运转

陈芳,高考之后我要学计算机专业,将来干IT发财了,我就娶你!

张小方

面试 薪资 程序员求职 程序员买房 毕业

原来 JavaScript 中的 WeakMap 是这样子的

pingan8787

Java 前端 Web

架构师训练营-week5-作业

晓-Michelle

极客大学架构师训练营

架构师训练营 第五周 基于虚拟节点的一致性Hash算法作业

且听且吟

极客大学架构师训练营

Week05作业

熊威

2021 ThoughtWorks 技术雷达峰会

2021 ThoughtWorks 技术雷达峰会

非RESTful的微软REST API指南-InfoQ