开发者社区> 晚来风急> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

非 RESTful 的微软 REST API 指南

简介:
+关注继续查看

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

文章转载自 开源中国社区[http://www.oschina.net]

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
Web API 版本控制的几种方式
http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html 这篇文章写得很好,介绍了三种实现web api版本化的三种方式。
1196 0
使用ASP.NET WEB API构建基于REST风格的服务实战系列教程(一)——使用EF6构建数据库及模型
原文:使用ASP.NET WEB API构建基于REST风格的服务实战系列教程(一)——使用EF6构建数据库及模型 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 使用Entity Framework Code First模式构建数据库对象 已经决定使用EF CodeFirst来创建数据库了,因此我们使用POCO类(“Plain Old CLR Objects)来定义我们的Model。
856 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【二】——使用Repository模式构建数据库访问层
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【二】——使用Repository模式构建数据库访问层 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 在数据访问层应用Repository模式来隔离对领域对象的细节操作是很有意义的。
887 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【三】——Web Api入门
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【三】——Web Api入门 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 经过前2节的介绍,我们已经把数据访问层搭建好了,从本章开始就是Web Api部分了。
1176 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【四】——实现模型工厂,依赖注入以及格式配置
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【四】——实现模型工厂,依赖注入以及格式配置 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 在上一篇中,我们已经初步开始使用Web Api了,但同时出现了一些很多不足之处,本章我们就着重来解决这些不足。
1147 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【五】——在Web Api中实现Http方法(Put,Post,Delete)
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【五】——在Web Api中实现Http方法(Put,Post,Delete) 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 在Web Api中,我们对资源的CRUD操作都是通过相应的Http方法来实现——Post(新增),Put(修改),Delete(删除),Get(查询)。
820 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【六】——实现资源间的关联
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【六】——实现资源间的关联 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 这一篇文章主要介绍一下资源间的关联——例如在学生和课程之间就存在这样的关联:每一个...
935 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【七】——实现资源的分页
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【七】——实现资源的分页 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 这篇文章我们将使用不同的方式实现手动分页(关于高端大气上档次的OData本文暂不涉及,但有可能会在系列的后期介绍,还没确定。
1110 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【九】——API变了,客户端怎么办?
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【九】——API变了,客户端怎么办? 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 一旦我们将API发布之后,消费者就会开始使用并和其他的一些数据混在一起。
847 0
使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【八】——Web Api的安全性
原文:使用ASP.NET Web Api构建基于REST风格的服务实战系列教程【八】——Web Api的安全性 系列导航地址http://www.cnblogs.com/fzrain/p/3490137.html 前言 这一篇文章我们主要来探讨一下Web Api的安全性,到目前为止所有的请求都是走的Http协议(http://),因此客户端与服务器之间的通信是没有加密的。
1254 0
+关注
文章
问答
文章排行榜
最热
最新
相关电子书
更多
API 平台的安全实践
立即下载
阿里云 API 精选手册(Alibaba Cloud API Playbook)
立即下载
API 网关实践
立即下载