HTTP API 设计指南(基础部分)
2016-07-28 11:19
387 查看
前言
这篇指南介绍描述了 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
相关文章推荐
- OkHttp的使用
- 从tcp原理角度理解Broken pipe和Connection reset by peer的区别
- 从tcp原理角度理解Broken pipe和Connection reset by peer的区别
- 对希拉里泄露邮件进行简单分析的结果
- WEB服务器、应用程序服务器、HTTP服务器区别
- linux PATH环境变量全解析--转自http://www.2cto.com
- 【Java TCP/IP Socket】UDP Socket(含代码)
- HttpSessionBindingListener的使用
- RESTful API 设计指南
- 找工作之计算机网络复习
- 计算机网络单位换算
- 玩转Android Camera开发(五):基于Google自带算法实时检测人脸并绘制人脸框(网络首发,附完整demo)
- http error
- 转:VMware中三种网络连接的区别
- 网络请求xml PULL解析
- http://t.cn/xx 等链接的生成与还原
- 网络知识之七 httpclient 访问第三方服务的时候导致 connection reset
- 用vs调试项目的时候报HTTP 错误 403.14 - Forbidden
- Linux-Tcp-IP
- Http协议详解