前言
前面我们说了,有章可循,有据可依,有正确的产品流程和规范,我们的工作才不至于产生混乱,团队的工作才能更有成效。我们经常见到,程序开发可能只用了半个月,但是接口的联调却经常需要花费半个月甚至一个月左右。
如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本。那么什么是好的API设计?这里我们不得不提到REST API。
另外,REST API的书籍很多,但是完整完善实践丰富的设计指导并不多见,我们有幸看到了微软团队的作品——Microsoft REST API Guidelines,因此才有了此篇内容。由于公众号文章内容字数有限,接下来我们会将翻译稿拆分并分享出来。翻译的不对之处,请多多指教。
什么是REST API?
Rest不是一种协议,也不是一种文字格式,更不是一种开发框架,它是一种系列的设计约束的集合:无状态性、将超媒体作为应用状态的引擎,这个约束我们统称Fielding约束。也就是说,它是一种软件架构风格、设计风格。它的两大核心理念是资源和表述,这个能加快我们对它的理解,然而REST -- REpresentational State Transfer,英语的直译就是“表现层状态转移”。
简单的来说,在REST API:URL定位资源,用HTTP动词(GET,POST,PUT,DELETE)描述操作。前面说了,REST 指的是一组架构约束条件和原则。那么满足这些约束条件和原则的应用程序或设计就是 RESTful。
为什么用REST API?
1.前后端分离主要以API为界做接洽的,这样就会有很多的API,API的表现力更强,更加便于理解。
2.REST API没有状态,不管前端是何种状态何种设备下都可以无差别的请求资源。
3.Restful API有直接的规范和原则。
简单的来说,有以下好处:
看到Url就知道可以拿到什么。
看到Http请求方法就知道要做什么。
看到Http状态码就知道干的怎么样了。
Microsoft REST API Guidelines目录
1 Abstract 摘要
2 Table of contents 目录表
3 Introduction 介绍
3.1 Recommended reading 推荐阅读
4 Interpreting the guidelines 解读指导
4.1 Application of the guidelines 应用指导
4.2 Guidelines for existing services and versioning of services 现有服务指南和服务版本化
4.3 Requirements language 要求的语言
4.4 License 许可证
5 Taxonomy 分类
5.1 Errors 错误
5.2 Faults 故障
5.3 Latency 潜在因素
5.4 Time to complete 完成时间
5.5 Long running API faults 长期运行的API故障
6 Client guidance 客户指导
6.1 Ignore rule 忽略规则
6.2 Variable order rule 变量排序规则
6.3 Silent fail rule 无声失效规则
7 Consistency fundamentals 一致性基础
7.1 URL structure 网址结构
7.2 URL length 网址长度
7.3 Canonical identifier 标准标识符
7.4 Supported methods 支持方法
7.5 Standard request headers 标准请求请求头
7.6 Standard response headers 响应请求头
7.7 Custom headers 自定义请求头
7.8 Specifying headers as query parameters 指定头部为查询参数
7.9 PII parameters PII参数
7.10 Response formats 响应格式
7.11 HTTP Status Codes HTTP状态码
7.12 Client library optional 可选的客户端库
8 CORS cors
8.1 Client guidance 客户端指导
8.2 Service guidance 服务指导
9 Collections 集合
9.1 Item keys 项的key
9.2 Serialization 序列化
9.3 Collection URL patterns 集合URL模式
9.4 Big collections 大集合
9.5 Changing collections 修改集合
9.6 Sorting collections 集合排序
9.7 Filtering 过滤
9.8 Pagination 分页
9.9 Compound collection operations 复合集合操作
10 Delta queries 增量查询
10.1 Delta links 增量链接
10.2 Entity representation 实体表示
10.3 Obtaining a delta link 获得增量链接
10.4 Contents of a delta link response 增量链接响应内容
10.5 Using a delta link 使用增量链接
11 JSON standardizations JSON标准化
11.1 JSON formatting standardization for primitive types 主要类型的JSON格式化标准化
11.2 Guidelines for dates and times 日期和时间指南
11.3 JSON serialization of dates and times 日期和时间的JSON序列化
11.4 Durations 持续时间
11.5 Intervals 间隔
11.6 Repeating intervals 重复间隔
12 Versioning 版本
12.1 Versioning formats 版本格式
12.2 When to version 版本的时间
12.3 Definition of a breaking change 非延续性更改的定义
13 Long running operations 长时间运行的操作
13.1 Resource based long running operations (RELO) 基于资源的长时间运行(RELO)
13.2 Stepwise long running operations 分步运行的长时间操作
13.3 Retention policy for operation results 操作结果保留策略
14 Push notifications via webhooks 通过webhooks推送通知
14.1 Scope 范围
14.2 Principles 原则
14.3 Types of subscriptions 订阅类型
14.4 Call sequences 调用序列
14.5 Verifying subscriptions 验证订阅
14.6 Receiving notifications 接收通知
14.7 Managing subscriptions programmatically programmatically订阅管理
14.8 Security 安全性
15 Unsupported requests 不支持的请求
15.1 Essential guidance 基本指导
15.2 Feature allow list 特征允许列表
16 Naming guidelines 命名准则
16.1 Approach 途径
16.2 Casing 框架
16.3 Names to avoid 避免的命名
16.4 Forming compound names 规范的复合词
16.5 Identity properties 标识属性
16.6 Date and time properties 日期和时间属性
16.7 Name properties 属性名
16.8 Collections and counts 集合和计数
16.9 Common property names 共同属性命名
17 Appendix 附录
17.1 Sequence diagram notes 时序图注释