Openapi 接口設計思路

Open API即開放API,也稱開放平台。所謂的開放API（OpenAPI）是服務型網站常見的一種應用，網站的服務商将自己的網站服務封裝成一系列API（Application Programming Interface，應用程式設計接口）開放出去，供第三方開發者使用，這種行為就叫做開放網站的API，所開放的API就被稱作OpenAPI（開放API）。

以前的軟體開發都是針對特定的使用者或群體進行設計,但使用者的需求是千差萬别的,衆口難調就是這個道理。随着軟體開發的發展,人們的關注點和設計模式也在悄悄發生着變化,我與其針對特定客戶進行開發,不如站在大衆的角度進行設計,把自己從甲方乙方的魔咒中解禁出來,自己成為甲方。也就是說我以前開發的軟體隻給你用,你還不滿意,現在我隻提供核心業務,你自己來對接,你想設計成什麼樣子就設計成什麼樣子。于是 Opean Api 應運而生！！淘寶、阿裡、騰訊都是這麼幹的,人家是大公司,規則的制定者,人家怎麼規定接口,你就得怎麼對接！！有一個網站叫 聚合資料 專門提供一些免費的和收費的優秀 API,有興趣的可以上去注冊玩玩。

關于如何開發這樣的一套接口,刨除實際的業務邏輯不說,我們來看看怎麼設計?可能不全面僅供參考!

先來看看有那幾點需要考量?我也是憑經驗和 Google。

簽名鑒權（我需要知道請求我的是誰,有沒有通路這個接口的權限）

流量控制（我不可能讓你随随便便就無節制的通路我,我要能随時關停你）

請求轉發（請求過來的 url,需要找到真正的業務處理邏輯,api最好隻負責接口的規範,不負責業務的實作）

日志處理（你可以保持沉默,但你說的每一句話都會成為呈堂供證）

異常處理（即使老子内部出了問題,你也不會看到我的異常堆棧資訊,我會告訴你我病了,請稍後再試）

參數規範（順我者倡,逆我者亡）

多機部署（我有九條命）

異步回調（别想阻塞我,但我可以玩死你）

錯誤資訊（你要認識到自己錯誤）

做API,尤其是 Open API 最重要的就是安全、安全、安全,試想一下,你的接口我可以随随便便就猜對賬号密碼,随随便便就可以DDOS 你,你都沒有辦法保證使用者資訊的安全,誰還敢用你。其實你是在做一件反黑客的設計,呵呵,是不是高大尚了很多。

Client:你怎麼知道一個請求是我而不是别人呢?

API:你如果對接我,我給你起一個全世界唯一名字就吧,你請求的時候就告訴我你叫 xxx,指派到請求中的app_key中就行,至于這個字段叫app_key還是叫 UserName還是叫 client_id,這個看你心情了。于是就有了接口的第一個功能,給客戶起一個唯一名字。

Client:如果别人也知道了這個使用者名,冒充我怎麼辦?

API:我還會給你一個配套的密碼,密碼隻有你我知道,你請求的時候,把密碼帶過來,我先驗證密碼,密碼通過了我才允許通路。這樣就沒人能冒充的了你了吧。你密碼丢了,那就是你自己的事情了。

Client:現在 HTTP 都是明文通信,我每次通路都帶上我的賬号密碼,那不等于廣而告之天下嗎?就像拿着一袋子錢在路上邊走邊喊“快來搶我呀！快來搶我呀！”，一個小小的嗅探器就能把使用者的密碼拿到手，如果使用者習慣在所有地方用一個密碼，那麼你闖大禍了，黑客通過撞庫的方法能把使用者的所有資訊一鍋端。

API:那就就用你的賬号密碼先到我這兒換取一個密碼吧,我們叫 token,這樣攜帶密碼且密碼正确的我們就認,沒有攜帶密碼或密碼不正确的我們幾回絕,這樣你就不用帶着密碼滿世界跑了。

Client:但是那如果 Token 被截獲了呢？黑客重放怎麼辦！！

API:這個密碼是有一個過期時間的比如10分鐘、一個小時、一天、3個月等等,你們也可以做到單點登入,我這邊也可以有效的控制外人的入侵,同時避免了重複資訊的反複查詢資料庫和對比等操作,絕對可以提高響應速度,校驗 token 的有效性花費的時間絕對比查資料庫要來的快啊。我們在伺服器端接口被調用時就可以對發起請求的ip位址、user-agent之類的資訊作比對，以防止僞造。再然後，如果token的有效期設得小，過一會兒它就過期了，除非黑客可以持續截獲你的token，否則他隻能幹瞪眼。

Client:這個可以,但是我第一次輸入密碼的時候還是有可能被竊取啊?

API:那就上 HTTPS ,密碼什麼的用 SSL 加密協定傳輸,我看誰還能竊取到呢?你要還糾結呢咱就上非對稱?

Client:…

API:還有話說麼?沒話說就老老實實對接

網絡攻防

CORS

CSRF

劫持攻擊

DDOS

XSS

SQL注入

檔案上傳漏洞

緩沖區溢出

如何設計一個符合 RESTful 的 OpenAPI

協定

API 與使用者的通信協定，建議使用 HTTPs 協定。

域名

應該盡量将 API 部署在專用域名之下。

https://api.example.com
           

如果确定 API 很簡單，不會有進一步擴充，可以考慮放在主域名下。

https://example.org/api/
           

版本（Versioning）

應該将 API 的版本号放入URL。

https://api.example.com/v1/
           

另一種做法是，将版本号放在 HTTP 頭資訊中，但不如放入 URL 友善和直覺。Github 采用這種做法。
           

路徑（Endpoint）

路徑又稱"終點"（endpoint），表示 API 的具體網址。

在 RESTful 架構中，每個網址代表一種資源（resource），是以網址中不能有動詞，隻能有名詞，而且所用的名詞往往與資料庫的表格名對應。一般來說，資料庫中的表都是同種記錄的"集合"（collection），是以 API 中的名詞也應該使用複數。

舉例來說，有一個 API 提供動物園（zoo）的資訊，還包括各種動物和雇員的資訊，則它的路徑應該設計成下面這樣。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
           

HTTP 動詞

對于資源的具體操作類型，由 HTTP 動詞表示。

常用的HTTP動詞有下面五個（括号裡是對應的SQL指令）。

GET（SELECT）：從伺服器取出資源（一項或多項）。
POST（INSERT）：在伺服器建立一個資源。
PUT（UPDATE）：在伺服器更新資源（用戶端提供改變後的完整資源）。
PATCH（UPDATE）：在伺服器更新資源（用戶端提供改變的屬性）。
DELETE（DELETE）：從伺服器删除資源。
           

還有兩個不常用的 HTTP 動詞。

HEAD：擷取資源的中繼資料。

OPTIONS：擷取資訊，關于資源的哪些屬性是用戶端可以改變的。

下面是一些例子。

GET /zoos：列出所有動物園POST /zoos：建立一個動物園
GET /zoos/ID：擷取某個指定動物園的資訊
PUT /zoos/ID：更新某個指定動物園的資訊（提供該動物園的全部資訊）
PATCH /zoos/ID：更新某個指定動物園的資訊（提供該動物園的部分資訊）
DELETE /zoos/ID：删除某個動物園
GET /zoos/ID/animals：列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID：删除某個指定動物園的指定動物
           

過濾資訊（Filtering）

如果記錄數量很多，伺服器不可能都将它們傳回給使用者。API應該提供參數，過濾傳回結果。

下面是一些常見的參數。

?limit=10：指定傳回記錄的數量?offset=10：指定傳回記錄的開始位置。
?page=2&per_page=100：指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：指定傳回結果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件
           

參數的設計允許存在備援，即允許API路徑和URL參數偶爾有重複。比如，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。

狀态碼（Status Codes）

伺服器向使用者傳回的狀态碼和提示資訊，常見的有以下一些（方括号中是該狀态碼對應的 HTTP 動詞）。

200 OK - [GET]：伺服器成功傳回使用者請求的資料，該操作是幂等的（Idempotent）。201 CREATED - [POST/PUT/PATCH]：使用者建立或修改資料成功。
202 Accepted - [*]：表示一個請求已經進入背景排隊（異步任務）
204 NO CONTENT - [DELETE]：使用者删除資料成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：使用者發出的請求有錯誤，伺服器沒有進行建立或修改資料的操作，該操作是幂等的。
401 Unauthorized - [*]：表示使用者沒有權限（令牌、使用者名、密碼錯誤）。
403 Forbidden - [*] 表示使用者得到授權（與401錯誤相對），但是通路是被禁止的。
404 NOT FOUND - [*]：使用者發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是幂等的。
406 Not Acceptable - [GET]：使用者請求的格式不可得（比如使用者請求JSON格式，但是隻有XML格式）。
410 Gone -[GET]：使用者請求的資源被永久删除，且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]：伺服器發生錯誤，使用者将無法判斷發出的請求是否成功。
           

狀态碼的完全清單參見這裡。

錯誤處理（Error handling）

如果狀态碼是4xx，就應該向使用者傳回出錯資訊。一般來說，傳回的資訊中将error作為鍵名，出錯資訊作為鍵值即可。

{    error: "Invalid API key"
}
           

傳回結果

針對不同操作，伺服器向使用者傳回的結果應該符合以下規範。

GET /collection：傳回資源對象的清單（數組）GET /collection/resource：傳回單個資源對象
POST /collection：傳回新生成的資源對象
PUT /collection/resource：傳回完整的資源對象
PATCH /collection/resource：傳回完整的資源對象
DELETE /collection/resource：傳回一個空文檔
           

Hypermedia API

RESTful API 最好做到 Hypermedia，即傳回結果中提供連結，連向其他 API 方法，使得使用者不查文檔，也知道下一步應該做什麼。

比如，當使用者向 api.example.com 的根目錄送出請求，會得到這樣一個文檔。

{"link": {  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}
           

上面代碼表示，文檔中有一個link屬性，使用者讀取這個屬性就知道下一步該調用什麼API了。

rel 表示這個 API 與目前網址的關系（collection 關系，并給出該 collection 的網址），href 表示 API 的路徑，title 表示 API 的标題，type 表示傳回類型。

Hypermedia API 的設計被稱為 HATEOAS。Github 的 API 就是這種設計，通路api.github.com會得到一個所有可用API的網址清單。

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
           

從上面可以看到，如果想擷取目前使用者的資訊，應該去通路api.github.com/user，然後就得到了下面結果。

{  "message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}
           

上面代碼表示，伺服器給出了提示資訊，以及文檔的網址。

點一下在看再走吧