微软HTTP API指南
来源:互联网 发布:数据透视表实例 编辑:程序博客网 时间:2024/06/10 06:29
微软发布了创建“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。
原文地址:http://www.infoq.com/cn/news/2016/07/microsoft-rest-api
.NET社区新闻,深度好文,微信中搜索dotNET跨平台或扫描二维码关注
- 微软HTTP API指南
- HTTP API 设计指南
- HTTP API 设计指南
- HeroKu的HTTP API 设计指南(中文版)
- 来自HeroKu的HTTP API 设计指南(中文版)
- 来自 HeroKu 的 HTTP API 设计指南(中文版)
- 来自HeroKu的HTTP API 设计指南(中文版)
- 微软面试指南
- directShow 编程指南 微软
- 微软随.NET 4.5发布新REST API框架(http://www.infoq.com/cn/news/2012/09/rest-web-api)
- 微软crypto API
- 微软在线翻译API试用
- 微软翻译api接口
- http://www.ruanyifeng.com/blog/2014/05/restful_api.html RESTful API 设计指南
- Java API设计指南
- Java API设计指南
- Java API设计指南
- Java API设计指南
- 分布式基础通信协议:paxos,totem和gossip
- 使用Visual Studio 2015 开发ASP.NET MVC 5 项目部署到Mono/Jexus
- 打造自己的LinqProvider
- Aaron Stannard谈Akka.NET 1.1
- 使用Akka.net开发第一个分布式应用
- 微软HTTP API指南
- docker4dotnet #3 .net猿和小鲸鱼的苹果山之旅
- 使用TF-IDF对Tweets做summarization
- .NET Core 工具遥测(应用信息收集)
- 分布式系统事务一致性解决方案大对比,谁最好使?
- 在.NET Core中使用MySQL5.7的JSON类型字段
- 我为什么用docker-compose来打包开发环境
- 生活随意行,创新看我的,带给你不一样的千牛登陆
- .NET Core扩展IServiceCollection自动注册服务