前言
前面我们说了，有章可循，有据可依，有正确的产品流程和规范，我们的工作才不至于产生混乱，团队的工作才能更有成效。我们经常见到，程序开发可能只用了半个月，但是接口的联调却经常需要花费半个月甚至一个月左右。
如果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
时序图注释