前言
前面我們說了，有章可循，有據可依，有正確的產品流程和規范，我們的工作才不至於產生混亂，團隊的工作才能更有成效。我們經常見到，程序開發可能只用了半個月，但是接口的聯調卻經常需要花費半個月甚至一個月左右。
如果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
時序圖注釋