微软发布了创建“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 》。
活动推荐:
2023年9月3-5日,「QCon全球软件开发大会·北京站」 将在北京•富力万丽酒店举办。此次大会以「启航·AIGC软件工程变革」为主题,策划了大前端融合提效、大模型应用落地、面向 AI 的存储、AIGC 浪潮下的研发效能提升、LLMOps、异构算力、微服务架构治理、业务安全技术、构建未来软件的编程语言、FinOps 等近30个精彩专题。咨询购票可联系票务经理 18514549229(微信同手机号)。
评论