HTTP API 设计指南(基础部分)
为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译
前言
这篇指南介绍描述了 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.
HTTP API 设计指南(基础部分)相关推荐
- RESTful API 设计指南[转]
一种软件架构风格.设计风格,而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. RESTful AP ...
- 组件接口(API)设计指南-文件夹
组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
- H5活动产品设计指南基础版
本文来自 网易云社区 . H5一般页面不会很多,看似简单,实际上会有很多细节需要注意,我自己在做过了几个H5之后,发现了一些常犯的问题,做了小结,希望给新开始做H5的产品相关的同学提供一些帮助. 首先 ...
- RESTful API 设计指南
原文地址:http://www.ruanyifeng.com/blog/2014/05/restful_api.html RESTful API 设计指南 作者: 阮一峰 日期: 2014年5月22日 ...
- 服务端指南 | 良好的 API 设计指南
设计一套良好的 API 接口. 原文地址:服务端指南 | 良好的 API 设计指南 博客地址:blog.720ui.com/ 版本号 在 RESTful API 中,API 接口应该尽量兼容之前的版本 ...
- Google API 设计指南 - 前言
原文地址:https://cloud.google.com/apis... Copyright: Creative Commons Attribution 3.0 License Current Ve ...
- google api设计指南-简介
简介 这是联网 API 的通用设计指南.它自 2014 年起在 Google 内部使用,是 Google 在设计 Cloud API 和其他 Google API 时遵循的指南.此设计指南在此处共享, ...
- Google API 设计指南-设计模式
翻译自 API Design Guide - Design Patterns 空响应体 标准的 Delete 方法 必须(must) 返回 google.protobuf.Empty 来实现全局一致性 ...
最新文章
- 《用户至上:用户研究方法与实践(原书第2版)》一 3.4 法律层面的考虑
- C语言再学习 -- 运算符与表达式
- c++string替换指定位置字符_Excel数据分析:如何替换字符串中的指定字符?
- IDEA无法加载log文件
- Flow vs Jenkins 实操对比,如何将Java应用快速发布至ECS
- Java中抽象类和接口的区别?
- 03-谷歌浏览器安装Sence
- python基础教程-北大学霸自学这套Python教程,7天开发12款游戏,堪称宝藏教程
- ValueError: Object arrays cannot be loaded when allow_pickle=False 报错解决
- 三本学计算机没用吗,腾讯员工:我211学计算机都觉得写代码难,三本的人能写代码为啥考不上211...
- nero linux刻录教程,nero刻录数据光盘的图文教程
- 产品经理应具备的能力(初中高级),产品经理岗位细分
- Linux下修复U盘坏块,快速修复U盘坏块
- crontab任务误删恢复及备份步骤
- HEG运行错误:GetBeginAndEndLocs
- 电信业务经营许可年报流程图文指南,教你年报怎么填
- ElasticSearch 数据迁移
- 5分钟学会Linux上传文件和下载文件命令
- Redis集群模式源码分析
- 有什么占内存小又好玩的手游,占内存小的手机游戏