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