HTTP API 设计指南(基础部分)
前言
这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Heroku 平台的 API 设计指引 Heroku 平台 API 指引。
这篇指南除了详细介绍现有的 API 外,Heroku 将来新加入的内部 API 也会符合这种设计模式,我们希望非 Heroku 员工的API设计者也能感兴趣。
我们的目标是保持一致性,专注业务逻辑同时避免过度设计。我们一直试图找出一种良好的、一致的、显而易见的 API 设计方法,而并不是所谓的"最终/理想模式"。
我们假设你熟悉基本的 HTTP+JSON API 设计方法,所以本篇指南并不包含所有的 API 设计基础。
我们欢迎你为这篇指南做贡献。
隔离关注点
设计时通过将请求和响应之间的不同部分隔离来让事情变得简单。保持简单的规则让我们能更关注在一些更大的更困难的问题上。
请求和响应将解决一个特定的资源或集合。使用路径(path)来表明身份,body来传输内容(content)还有头信息(header)来传递元数据(metadata)。查询参数同样可以用来传递头信息的内容,但头信息是首选,因为他们更灵活、更能传达不同的信息。
强制使用安全连接(Secure Connections)
所有的访问API行为,都需要用 TLS 通过安全连接来访问。没有必要搞清或解释什么情况需要 TLS 什么情况不需要 TLS,直接强制任何访问都要通过 TLS。
理想状态下,通过拒绝所有非 TLS 请求,不响应 http 或80端口的请求以避免任何不安全的数据交换。如果现实情况中无法这样做,可以返回403 Forbidden
响应。
把非 TLS 的请求重定向(Redirect)至 TLS 连接是不明智的,这种含混/不好的客户端行为不会带来明显好处。依赖于重定向的客户端访问不仅会导致双倍的服务器负载,还会使 TLS 加密失去意义,因为在首次非 TLS 调用时,敏感信息就已经暴露出去了。
强制头信息 Accept 中提供版本号
制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以,最好在设计之初就使用一些方法来预防可能会遇到的问题。
为了避免API的变动导致用户使用中产生意外结果或调用失败,最好强制要求所有访问都需要指定版本号。请避免提供默认版本号,一旦提供,日后想要修改它会相当困难。
最适合放置版本号的位置是头信息(HTTP Headers),在 Accept
段中使用自定义类型(content type)与其他元数据(metadata)一起提交。例如:
Accept: application/vnd.heroku+json; version=3
支持Etag缓存
在所有返回的响应中包含ETag
头信息,用来标识资源的版本。这让用户对资源进行缓存处理成为可能,在后续的访问请求中把If-None-Match
头信息设置为之前得到的ETag
值,就可以侦测到已缓存的资源是否需要更新。
为内省而提供 Request-Id
为每一个请求响应包含一个Request-Id
字段,并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值,它能主我们提供一种机制来跟踪、诊断和调试请求。
通过请求中的范围(Range)拆分大的响应
一个大的响应应该通过多个请求使用Range
头信息来拆分,并指定如何取得。详细的请求和响应的头信息(header),状态码(status code),范围(limit),排序(ordering)和迭代(iteration)等,参考Heroku Platform API discussion of Ranges.
原文:
https://segmentfault.com/a/1190000002511720
HTTP API 设计指南(基础部分)的更多相关文章
- 来自HeroKu的HTTP API 设计指南(中文版)
原文转自:http://get.jobdeer.com/343.get 来自HeroKu的HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国内 ...
- Rest Framework简介 和 RESTful API 设计指南
使用Django Rest Framework之前我们要先知道,它是什么,能干什么用? Django Rest Framework 是一个强大且灵活的工具包,用以构建Web API 为什么要使用Res ...
- [置顶]
来自 HeroKu 的 HTTP API 设计指南(中文版)
转载:http://get.jobdeer.com/343.get 来自 HeroKu 的 HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国 ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
- 组件接口(API)设计指南-文件夹
组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...
- RESTFul API设计指南及使用说明
RESTFul API设计指南及使用说明 一. 协议 API与用户的通信协议,使用HTTP协议. 二. 域名 应尽量将API部署在专用域名之下(http://api.example.com) 也可以将 ...
- RESTful API 设计指南,RESTful API 设计最佳实践
RESTful API 设计指南,RESTful API 设计最佳实践 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). ...
- H5活动产品设计指南基础版
本文来自 网易云社区 . H5一般页面不会很多,看似简单,实际上会有很多细节需要注意,我自己在做过了几个H5之后,发现了一些常犯的问题,做了小结,希望给新开始做H5的产品相关的同学提供一些帮助. 首 ...
- API设计指南(译)
API的设计在软件系统中的重要性不言而喻,在swift.org上看到一篇“API Design Guidelines”,虽然是就Swift而言,但对于其它语言也有不少可以借鉴的地方,在这里粗略翻译一二 ...
- 理解RESTful架构——Restful API设计指南
理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...
随机推荐
- 百度UEditor富文本编辑器去除过滤div等标签
将设计排版好的页面html代码上传到数据库,再读取出来的时候发现所有的div都被替换成了p标签. 解决方法: 首先在ueditor.all.js文件内搜索allowDivTransToP,找到如下的代 ...
- ASP.NET Web API使用示例
原文地址:https://blog.csdn.net/chinacsharper/article/details/21333311 上篇博客讲解rest服务开发时,曾经提到过asp.net mvc中的 ...
- Python练习笔记——编写一个装饰器,测算出一个函数的运行时间
import time def time_value(dec): def wrapper(*args,**kwargs): start_time = time.time() get_str = dec ...
- python dataframe 在merge时 产生笛卡尔积
在pandas中,concat, merge, join的使用方法可以参考以下资料: http://blog.csdn.net/stevenkwong/article/details/52528616 ...
- 为训练深度OCR 图像,生成文本图像
https://github.com/Sanster/text_renderer Generate text images for training deep learning ocr model 在 ...
- Kali 2.0最新国内源:阿里云,中科大
版权声明:本文为博主原创文章,转载请注明来源. https://blog.csdn.net/liushulin183/article/details/51519628 刚刚要给kali装个中文输入法 ...
- 用VIM打造C语言编写器
1.先用vim --version命令查看一下都是安装了那些vim特性,以及版本等等情况. vim --version VIM - Vi IMproved 7.4 (2013 Aug 10, comp ...
- Statistical Concepts and Market Returns
Statistical Concepts and Market Returns Categories of statistics Descriptive statistics: used to sum ...
- 【Android】第18章 位置服务和手机定位—本章示例主界面
分类:C#.Android.VS2015: 创建日期:2016-03-04 一.简介 目前,基于位置的服务发展迅速,已涉及到商务.医疗.定位.追踪.敏感区域警告.工作和生活等各个方面.定位服务融合了G ...
- 一些通用性的haproxy调优tips
一.硬件和系统 haproxy是单线程,非阻塞,事件驱动,所以会最大化利用单个CPU内核,选择haproxy的硬件时要关注如下: 1.选择CPU的时候,选择高主频,大缓存的型号,比内核数更重要 2 ...