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架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...
随机推荐
- Eureka常见问题总结
在Spring-cloud做微服务架构时,会碰到各种坑.下面总结一下Eureka的常见问题. 一.Eureka的自我保护模式 如果在Eureka Server的首页看到以下这段提示,则说明Eure ...
- oc set/get方法
新建一个“Cocoa Touch Class”文件,命名为People People.h 写入 @interface People : NSObject @property int age; @end ...
- 摘:分配和释放BSTR的内存
当您创建 BSTR的并将它们使用以避免内存泄漏的它们在COM对象之间时,必须注意在将内存的. 当 BSTR 在接口中保持,必须释放其内存,当处理它. 但是,那么,当 BSTR ...
- AP_自动付款工作台设定和操作(流程)
2014-06-04 Created By BaoXinjian
- Linux内存初始化(一)
一.前言 一直以来,我都非常着迷于两种电影拍摄手法:一种是慢镜头,将每一个细节全方位的展现给观众.另外一种就是快镜头,多半是反应一个时代的变迁,从非常长的时间段中,截取几个典型的snapshot,合成 ...
- __attribute__中constructor和destructor
1.前言 最近看到一份代码,看到一个函数前面用__attribute__((destructor))修饰,当时感觉有点怪怪的,搜了整个程序,也没发现哪个地方调用这个函数.于是从字面意思猜想,该函数会在 ...
- jquery 事件注冊 与反复事件处理
<!doctype html> <html lang="us"> <head> <meta charset="utf-8&quo ...
- ubuntu中将某一程序设置为开机启动项的方法
一.简要说明 Linux操作系统的引导加载程序(对个人电脑而言通常是LILO)开始,介绍Linux开机引导的步骤. 加载内核LILO启动之后,如果你选择了Linux作为准备引导的操作系统,第一个被加载 ...
- Nginx访问PHP文件的File not found错误处理,两种情况
这个错误很常见,原有有下面两种几种 1. php-fpm找不到SCRIPT_FILENAME里执行的php文件 2. php-fpm不能访问所执行的php,也就是权限问题 第一种情况 可以在你的loc ...
- 集群瓶颈:磁盘IO必读
首先需要知道什么是IO: IO是输入输出接口阅读本文章可以带着下面问题1.集群的瓶颈为什么IO?2.你对IO了解多少? 这里面只说个人观点:当我们面临集群作战的时候,我们所希望的是即读即得.可是面对大 ...