OpenAPI 標準規(guī)范

什么是API規(guī)范

API 是模塊或者子系統(tǒng)之間交互的接口定義。好的系統(tǒng)架構離不開好的 API 設計，而一個設計不夠完善的 API 則注定會導致系統(tǒng)的后續(xù)發(fā)展和維護非常困難。在關鍵環(huán)節(jié)制定明確的API規(guī)范有助于 Service 對內提高產(chǎn)品間互通的效率，對外提供一致的使用體驗，也有助于更好地被集成。

對于API規(guī)范，比較知名的是 OpenAPI Specfication^[1] 和 Google API Design Guide^[2]。前者針對 RESTful API 設計在細節(jié)層面給出了非常具體的規(guī)定，已經(jīng)成為 RESTful API 設計領域的事實標準，而后者則主要從云廠商的角度提出許多最佳實踐性質的規(guī)范與建議，這些原則不僅僅適用于 RESTful API，也適合其他類型API設計。

雖然RESTful設計風格曝光率很高，但并不是所有云服務商都選擇了完全遵循RESTful，例如AWS和 阿里云^[3] RPC 風格反而占了大多數(shù)，Google和Azure則RESTful居多。

RESTful API的優(yōu)勢是HTTP具備更好的易用性，讓異構系統(tǒng)更容易集成，且開發(fā)執(zhí)行效率比較高，面向資源要求也比較高。而RPC API可以使用更廣泛的框架和方案，技術層面更底層也更為靈活，設計起來相對簡單，掌握起來有一定門檻，架構上更加復雜。RESTful 與 RPC 模式對比如下：

如果強制統(tǒng)一風格，有些適合 RESTful 風格的服務非要使用RPC的話，看起來就會比較丑陋，如果只是一個過程化的服務調用，往 RESTful 資源化設計方向去靠會比較困難。但如果不強制使用統(tǒng)一風格，會造成針對API的體系化支持會更加復雜，例如為兼容兩種風格SDK的自動化支持需要兩套代碼。

選擇API風格時要考慮幾個問題：

• 選擇支持哪種風格，才能更好地體現(xiàn)業(yè)務特性，讓客戶操作起來更加方便；
• 設計API時能否面向資源設計，相應的工程人員是否具備做這種設計的能力；
• 針對這種風格工具鏈的支持是否到位，投入產(chǎn)出比如何；
• 業(yè)界流行的趨勢如何，是否需要考慮與其他系統(tǒng)體系的互操作。

用戶使用API來訪問 Service，本質上是想通過對某種資源執(zhí)行特定的操作來完成一個業(yè)務動作。對于資源有兩個關鍵點：一是要有統(tǒng)一的資源模型；二是要明確資源關系。統(tǒng)一的資源模型對 Service 的幫助是巨大的：

• 它可以使API具有更清晰的結構，幫助用戶理解；
• 它可以幫助對比API與后臺實體關系模型，更容易提供更完整的API服務；
• 它可以使產(chǎn)品協(xié)作更加順暢，對資源的操作也更加規(guī)范化；
• 它可以使云服務底層平臺實現(xiàn)起來更統(tǒng)一、更方便；
• 它可以使圍繞API的生態(tài)集成起來更加簡單、高效。

確定了設計模式和資源模型后，就需要考慮 API的設計細節(jié)了，諸如API名稱、參數(shù)名、屬性名稱、數(shù)據(jù)格式、錯誤碼之類的信息。除此之外，還要考慮以下一些問題：

• 在API命名的時候，遵循什么樣的范式來確保大體風格相似？動詞、名詞、介詞如何組合才能保持API風格看起來比較統(tǒng)一，降低理解成本？
• 對于類似的操作，有沒有使用規(guī)范？有哪些公共的標準詞匯使得同類型的操作可以比較容易理解，避免使用晦澀奇怪的詞匯（例如讀操作，Read/Query/Describe/List/Get中都在什么場合使用什么動詞）？
• 被廣泛使用的參數(shù)如何盡可能保持一致，避免不同產(chǎn)品的表達混亂的情況（例如分頁參數(shù)用PageNumber還是PageNum）？
• 對于常用的場景，例如冪等、分頁、異步API的設計有沒有統(tǒng)一的規(guī)范，避免使用體驗不一致？
• 錯誤碼應該怎么設計？公共錯誤碼怎么統(tǒng)一，業(yè)務錯誤碼怎么表達？

上述問題都是實際研發(fā)過程中要注意的，要全部羅列的話遠不止這些。API的用詞描述是 Service 展現(xiàn)給外部用戶的第一印象，絕非隨意寫就。對人員有一定規(guī)模，內部有多條產(chǎn)品線的組織來說，如何協(xié)調組織的各個部分對外具有統(tǒng)一的體驗是個很大挑戰(zhàn)。

Service 在管理API時應該考慮一些具體的規(guī)范，對命名規(guī)則、標準詞匯、最佳實踐模式、錯誤碼等信息都有明確的規(guī)定，同時用系統(tǒng)化、平臺化的手段來管理API，確保不走偏。設計風格不是云服務API設計中致命的問題，但是它關乎云服務外表形象，不可不察。

API是后端服務的外部表達，是服務就有可能出現(xiàn)問題，無論這個問題是可預期的還是不可預期的。如果只考慮功能本身功能特性，而忽視對異常情況的設計，當問題出現(xiàn)的時候業(yè)務本身可能無法感知造成服務異常，更重要的是站在客戶角度去看，不能有效獲取錯誤原因是非常痛苦的，很多時候只能束手無策，降低云服務提供商的整體口碑，甚至損害營收。

OpenAPI規(guī)范

本規(guī)范基于 RESTful 風格的架構設計準則，廣泛參考 GitHub、Azure、Google API Design Guide、騰訊云、阿里云等公開資料，兼顧現(xiàn)有實際情況和未來發(fā)展做一個概括性記錄總結。

一、協(xié)議

API 與用戶的通信協(xié)議，總是使用 HTTPS 協(xié)議。這個和 RESTful API 本身沒有很大的關系，但是對于增加網(wǎng)站的安全是非常重要的。特別如果你提供的是公開 API，用戶的信息泄露或者被攻擊會嚴重影響網(wǎng)站的信譽。

二、版本（Version）

關于版本的設計有3種形式：

1. 將 API 的版本號放入 URL 中，如：http://api.example.com/v1，這樣方便和直觀；

2. 將版本號記錄在 url query中，如：http://api.example.com?param1=val&version=1.0中的 version 參數(shù)。

3. 將版本號放在 HTTP 頭信息中，基于的準則是：不同的版本，可以理解成同一種資源的不同形式，所以應該采用同一個URL。如：Accept: application/json; version=1.0，可以參考Github API Design^[4]和 Versioning REST Services^[5]；

根據(jù)現(xiàn)有的實際情況，如果是為了兼容已存在的服務接口，可以采用對應的形式。如果是新構建的體系結構，建議采用第三種。

三、Schema

URI的格式定義如下：URI = scheme "://" authority "/" path \[ "?" query \] \[ "#" fragment \]

URL 是 URI 的一個子集(一種具體實現(xiàn))，對于 REST API 來說一個資源一般對應一個唯一的 URI（URL）。在 URL 的設計中，我們會遵循一些規(guī)則，使接口看起透明易讀，方便使用者調用。

"/"分隔符一般用來對資源層級的劃分。對于 RESTful API 來說，"/"只是一個分隔符，并無其他含義。為了避免混淆，"/"不應該出現(xiàn)在URL的末尾。

URL 中盡量使用連字符"-"代替下劃線"_"的使用。 連字符"-"一般用來分割 URL 中出現(xiàn)的字符串(單詞)，來提高 URL 的可讀性，例如：http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post。使用下劃線"_"來分割字符串(單詞)可能會和鏈接的樣式?jīng)_突重疊，而影響閱讀性。但實際上，"-"和"_"對URL 中字符串的分割語意上還是有些差異的："-"分割的字符串(單詞)一般各自都具有獨立的含義，可參見上面的例子。而"_"一般用于對一個整體含義的字符串做了層級的分割，方便閱讀，例如你想在 URL 中體現(xiàn)一個 IP 地址的信息：210_110_25_88 . (歡迎關注：朱小廝的博客)

URL應該統(tǒng)一使用小寫字母。

URL中不要包含文件(腳本)的擴展名。例如 .json 之內的就不要出現(xiàn)了，對于接口來說沒有任何實際的意義。如果是想對返回的數(shù)據(jù)內容格式標示的話，通過 HTTP Header 中的 Content-Type 字段更好一些。

對于響應返回的格式，JSON 因為它的可讀性、緊湊性以及多種語言支持等優(yōu)點，成為了 HTTP API 最常用的返回格式。因此，最好采用 JSON 作為返回內容的格式。如果用戶需要其他格式，比如 xml，應該在請求頭部 Accept 中指定。對于不支持的格式，服務端需要返回正確的 status code，并給出詳細的說明。

JSON中的所有字段都應該用小寫的蛇形命名形式，而不是采用駝峰命名。

四、以資源為中心的 URL 設計

資源是 Restful API 的核心元素，所有的操作都是針對特定資源進行的。而資源就是 URL（Uniform Resoure Locator）表示的，所以簡潔、清晰、結構化的 URL 設計是至關重要的。Github 可以說是這方面的典范，下面我們就拿 repository 來說明：

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch

我們可以看到幾個特性：

• 資源分為單個文檔和集合，盡量使用復數(shù)來表示資源，單個資源通過添加 id 或者 name 等來表示
• 一個資源可以有多個不同的 URL
• 資源可以嵌套，通過類似目錄路徑的方式來表示，以體現(xiàn)它們之間的關系

最常見的一種設計錯誤，就是URL包含動詞。 因為"資源"表示一種實體，所以應該是名詞，URL 不應該有動詞，動詞應該放在 HTTP Method （參考下一條）中。舉例來說，某個 URL 是 /users/show/1，其中 show是動詞，這個 URL 就設計錯了，正確的寫法應該是 /users/1，然后用 HTTP GET 方法表示 show。

如果某些動作是HTTP 動詞表示不了的，你可以把動作看成是一種資源。比如網(wǎng)上匯款，從賬戶1向賬戶2匯款500元，錯誤的 URL 是：

POST?/accounts/1/transfer/500/to/2

正確的寫法是把動詞 transfer 改成transaction，資源不能是動詞，但是可以是一種服務：

POST??/transactoin?HTTP/1.1
HOST:?127.0.0.1

from=1&to=2&amount=500

五、正確使用 HTTP Method

有了資源的 URI 設計，所有針對資源的操作都是使用 HTTP 方法指定的。比較常用的 HTTP/1.1 動詞有下面5個：

• GET：從服務器取出資源（一項或多項）。
• POST：在服務器新建一個資源。
• PUT：在服務器更新資源（客戶端提供改變后的完整資源）。
• PATCH：在服務器更新資源（更新資源的部分屬性）。
• DELETE：從服務器刪除資源。

還有4個不常用的 HTTP/1.1 動詞：

• HEAD：只獲取某個資源的頭部信息。比如只想了解某個文件的大小，某個資源的修改日期等
• OPTIONS：獲取信息，關于資源的哪些屬性是客戶端可以改變的。
• TRACE：追蹤路徑。不建議使用。
• CONNECT：要求用隧道協(xié)議連接代理。不建議使用。

舉例：

GET?/repos/:owner/:repo/issues
GET?/repos/:owner/:repo/issues/:number
POST?/repos/:owner/:repo/issues
PATCH?/repos/:owner/:repo/issues/:number
DELETE?/repos/:owner/:repo

這里順帶探討一下，HTTP 協(xié)議涉及到的一種重要性質：冪等性(Idempotence)。在 HTTP/1.1 規(guī)范中冪等性的定義是：

Methods can also have the property of "idempotence" in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request.

從定義上看，HTTP 方法的冪等性是指一次和多次請求某一個資源應該具有同樣的副作用。冪等性屬于語義范疇，正如編譯器只能幫助檢查語法錯誤一樣，HTTP 規(guī)范也沒有辦法通過消息格式等語法手段來定義它，這可能是它不太受到重視的原因之一。但實際上，冪等性是分布式系統(tǒng)設計中十分重要的概念，而 HTTP 的分布式本質也決定了它在 HTTP 中具有重要地位。

安全方法是指不修改資源的 HTTP 方法。譬如，當使用 GET 或者 HEAD 作為資源 URL，都必須不去改變資源。然而，這并不全準確。意思是：它不改變資源的表示形式。對于安全方法，它仍然可能改變服務器上的內容或資源，但這必須不導致不同的表現(xiàn)形式。

實際上接口的冪等或者安全與否取決于接口的實現(xiàn)，只是 HTTP Method 語義上我們約定俗成地認為實現(xiàn)的過程會參照上表所示。對于冪等的接口，客戶端就可以放心地多次調用，網(wǎng)關層面也可以重試。

六、狀態(tài)碼 （Status Code）

HTTP 應答中，需要帶一個很重要的字段：status code。它說明了請求的大致情況，是否正常完成、需要進一步處理、出現(xiàn)了什么錯誤，對于客戶端非常重要。狀態(tài)碼都是三位的整數(shù)，大概分成了幾個區(qū)間：

• 2XX：請求正常處理并返回
• 3XX：重定向，請求的資源位置發(fā)生變化
• 4XX：客戶端發(fā)送的請求有錯誤
• 5XX：服務器端錯誤

在 HTTP API 設計中，經(jīng)常用到的狀態(tài)碼以及它們的意義如下表：

上面這些狀態(tài)碼覆蓋了 API 設計中大部分的情況，如果對某個狀態(tài)碼不清楚或者希望查看更完整的列表，可以參考 HTTP Status Code^[6] 、維基百科-狀態(tài)碼^[7]或者 RFC7231 Response Status Codes^[8] 的內容。

七、錯誤處理（Error Handling）

如果出錯，應該在 response body 中通過 message 給出明確的錯誤信息（一般來說，返回的信息中將 message 作為鍵名，出錯詳情作為鍵值即可）。比如客戶端發(fā)送的請求有錯誤，一般會返回 4XX Bad Request 結果。這個結果很模糊，給出錯誤 message 的話，能更好地讓客戶端知道具體哪里有問題，進行快速修改。

{
?"message":"錯誤詳情"
}

錯誤詳情應該可以幫助用戶輕松快捷地理解和解決API 錯誤。通常，在編寫錯誤詳情時請考慮以下準則：

• 不要假設用戶是您 API 的專家用戶。用戶可能是客戶端開發(fā)人員、操作人員、IT 人員或應用的最終用戶。
• 不要假設用戶了解有關服務實現(xiàn)的任何信息，或者熟悉錯誤的上下文（例如日志分析）。
• 如果可能，應構建錯誤詳情，以便技術用戶（但不一定是 API 開發(fā)人員）可以響應錯誤并改正。
• 確保錯誤詳情內容簡潔。如果需要，請?zhí)峁┮粋€鏈接，便于有疑問的讀者提問、提供反饋或詳細了解錯誤詳情中不方便說明的信息。此外，可使用詳細信息字段來提供更多信息。

八、命名規(guī)則

為了能夠長時間在眾多 API 中為開發(fā)者提供一致的體驗，API 使用的所有名稱都應該具有以下特點：

• 簡單
• 直觀
• 一致

這包括接口、資源、集合、方法和消息的名稱。

由于很多開發(fā)者不是以英語為母語，所以這些命名慣例的目標之一是確保大多數(shù)開發(fā)者可以輕松理解 API。對于方法和資源，我們鼓勵使用簡單、直觀和少量的詞匯來命名。

• API 名稱 應該 使用正確的美式英語。例如，使用美式英語的 license、color，而非英式英語的 licence、colour。
• 為了簡化命名， 可以 使用已被廣泛接受的簡寫形式或縮寫。例如，API 優(yōu)于 Application Programming Interface。
• 盡量使用直觀、熟悉的術語。例如，如果描述移除（和銷毀）一個資源，則刪除優(yōu)于擦除。
• 使用相同的名稱或術語命名同樣的概念，包括跨 API 共享的概念。
• 避免名稱過載。使用不同的名稱命名不同的概念。
• 避免在 API 的上下文以及更大的 API 生態(tài)系統(tǒng)中使用含糊不清且過于籠統(tǒng)的名稱。這些名稱可能導致對 API 概念的誤解。相反，應選擇能準確描述 API 概念的名稱。這對定義一階 API 元素（例如資源）的名稱尤其重要。沒有要避免使用的名稱的明確列表，因為每個名稱都必須放在其他名稱的上下文中進行評估。實例、信息和服務是過去有問題的名稱的示例。所選擇的名稱應清楚地描述 API 概念（例如：什么的實例？），并將其與其他相關概念區(qū)分開（例如：“alert”是指規(guī)則、信號還是通知？）。
• 仔細考慮是否使用可能與常用編程語言中的關鍵字相沖突的名稱。您可以使用這些名稱，但在 API 審核期間可能會觸發(fā)額外的審查。因此應謹慎使用。

九、認證和授權（Authentication & Authorization）

一般來說，讓任何人隨意訪問公開的 API 是不好的做法。驗證和授權是兩件事情：

• 驗證（Authentication）是為了確定用戶是其申明的身份，比如提供賬戶的密碼。不然的話，任何人偽造成其他身份（比如其他用戶或者管理員）是非常危險的
• 授權（Authorization）是為了保證用戶有對請求資源特定操作的權限。比如用戶的私人信息只能自己能訪問，其他人無法看到；有些特殊的操作只能管理員可以操作，其他用戶有只讀的權限等等

如果沒有通過驗證（提供的用戶名和密碼不匹配，token 不正確等），需要返回 401 Unauthorized^[9]狀態(tài)碼，并在 body 中說明具體的錯誤信息；而沒有被授權訪問的資源操作，需要返回 403 Forbidden^[10] 狀態(tài)碼，還有詳細的錯誤信息。

NOTES: 借鑒于 Github，它對某些用戶未被授權訪問的資源操作返回 404 Not Found^[11]，目的是為了防止私有資源的泄露（比如黑客可以自動化試探用戶的私有資源，返回 403 的話，就等于告訴黑客用戶有這些私有的資源）。

十、限流（RateLimit）

如果對訪問的次數(shù)不加控制，很可能會造成 API 被濫用，甚至被 DDOS 攻擊^[12]。根據(jù)使用者不同的身份對其進行限流，可以防止這些情況，減少服務器的壓力。

對用戶的請求限流之后，要有方法告訴用戶它的請求使用情況，本文檔推薦使用的三個相關的頭部：

• X-RateLimit-Limit: 用戶每個小時允許發(fā)送請求的最大值
• X-RateLimit-Remaining：當前時間窗口剩下的可用請求數(shù)目
• X-RateLimit-Rest: 時間窗口重置的時候，到這個時間點可用的請求數(shù)量就會變成 X-RateLimit-Limit 的值

舉例：

X-Ratelimit-Limit:?18000
X-Ratelimit-Remaining:?17995
X-Ratelimit-Reset:?1590570990

如果允許沒有登錄的用戶使用 API（可以讓用戶試用），可以把 X-RateLimit-Limit 的值設置得很小，比如 60。沒有登錄的用戶是按照請求的 IP 來確定的，而登錄的用戶按照認證后的信息來確定身份。

對于超過流量的請求，可以返回 429 Too many requests^[13] 狀態(tài)碼，并附帶錯誤信息。

十一、編寫優(yōu)秀的文檔

API 最終是給人使用的，不管是公司內部，還是公開的 API 都是一樣。即使我們遵循了上面提到的所有規(guī)范，設計的 API 非常優(yōu)雅，用戶還是不知道怎么使用我們的 API。最后一步，但非常重要的一步是：為你的 API 編寫優(yōu)秀的文檔。

對每個請求以及返回的參數(shù)給出說明，最好給出一個詳細而完整地示例，提醒用戶需要注意的地方……反正目標就是用戶可以根據(jù)你的文檔就能直接使用 API，而不是要發(fā)郵件給你，或者跑到你的座位上問你一堆問題。

參考資料