REST API设计指导——译自Microsoft REST API Guidelines（一）

前言

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

如果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  时序图注释