教年轻 AIoT 创业者如何从 0 到 1 实现AIoT 创业项目 了解详情
写点什么

非 RESTful 的微软 REST API 指南

  • 2016-07-27
  • 本文字数:1557 字

    阅读完需:约 5 分钟

微软发布了创建“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

活动推荐:

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

2016-07-27 19:006107
用户头像

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

关注

评论

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

产品和管理必备技能 Top 5

宇宙之一粟

产品 领导力 8月月更

云原生数据库白皮书,发布!

华为云开发者联盟

数据库 云原生 后端 华为云 白皮书

使用 OpenTelemetry 零代码修改接收 SkyWalking 追踪数据

Daocloud 道客

云原生 可观测性 Skywalking OpenTelemetry

封仲淹:OceanBase社区版4.0未来畅想

OceanBase 数据库

字节内部MySQL宝典意外流出!堪称数据库的天花板

退休的汤姆

Java、 面经 Java工程师 秋招 MySQL 数据库

阿里云 EMAS Serverless 重磅发布

hum建应用专家

云原生

【LeetCode】合并区间Java题解

Albert

LeetCode 8月月更

从InfluxDB到TDengine,阳光氢能为什么会做出这个选择?

TDengine

数据库 tdengine 时序数据库

Spring Security + Vue + Flowable 怎么玩?

江南一点雨

Java spring springsecurity flowable

【有奖评测局】阿里云容器镜像 ACR 测评团限时招募中!

阿里巴巴中间件

阿里云 云原生 容器镜像

MSE 费芮新金融行业标杆案例

阿里巴巴中间件

阿里云 微服务 云原生

SAP Fiori Launchpad Tile,UI5 应用,和 PFCG Role 的对应关系

Jerry Wang

SAP Fiori Launchpad ui5 8月月更

为什么 DevOps 会失败?

SoFlu软件机器人

即时通讯安全篇(十):IM聊天系统安全手段之通信连接层加密技术

JackJiang

网络安全 https 网络编程 即时通讯 SSL/TLS

企业引进外部专家合作开发时,如何保证数字资产既开放又安全?

ModelWhale

数字化转型 数据安全 资产安全 技术专家 协同开发

如何做好分支管理,保证高效CI/CD?

华为云开发者联盟

git 开发

J2EE进阶(三)struts2 <s:action>标签的用法及Spring在web.xml中的配置

No Silver Bullet

spring Struts2 8月月更 <s:action>

「数澈软件」获5300万元种子轮融资,构建新一代软件供应链防火墙

SEAL安全

软件供应链安全

创建第一个 Cypress 应用后使用命令行 npx Cypress open 报错的原因分析

Jerry Wang

前端开发 自动化测试 Cypress web开发 8月月更

易周金融分析 | Q2手机银行活跃用户环比增长2.17%

易观分析

金融 手机银行

2022 OceanBase数据库大赛开启,30W奖金等你来拿!

OceanBase 数据库

ModelBox开发体验:使用YOLOv3做口罩检测

华为云开发者联盟

人工智能 ModelBox

企业如何跨部门实现模型应用全生命周期管理

ModelWhale

数字化转型 应用模型 迭代管理 跨部门沟通 算法模型

企业如何将自身的数字技术及研究成果快速对外发布应用

ModelWhale

数字化转型 部署 应用模型 对外接口 协同开发

芯声智能亮相亚洲智能穿戴展,智能头盔声学方案为骑手保驾护航

硬科技星球

开源一夏 | STM32对接涂鸦wifi模块项目(智能插座-开源)

矜辰所致

开源 stm32 WiFi物联网智能插座 8月月更 涂鸦智能

SAP AMDP 介绍 - ABAP 托管的 HANA 数据库过程

Jerry Wang

数据库 SAP abap 8月月更 AMDP

精妙绝伦!10年阿里工作经验总结出这份亿级高并发系统设计手册,真的太强了!

退休的汤姆

Java、 面经 社招 Java工程师 秋招

企业数字化转型,如何实现业务部门与算法部门共同探索模型开发优化

ModelWhale

数据分析 工作流 数字化转型 业务思维 协同开发

开源一夏 | 如何在 JavaScript 中创建虚拟键盘

海拥(haiyong.site)

JavaScript 开源 前端 8月月更

Go-Excelize API源码阅读(十七)——GetPageLayout、SetPageMargins

Regan Yue

Go 开源 源码解析 8月日更 8月月更

  • 扫码添加小助手
    领取最新资料包
非RESTful的微软REST API指南_REST_Abel Avram_InfoQ精选文章