Open API即開(kāi)放API,也稱開(kāi)放平臺(tái)。 所謂的開(kāi)放API（OpenAPI）是服務(wù)型網(wǎng)站常見(jiàn)的一種應(yīng)用俄讹，網(wǎng)站的服務(wù)商將自己的網(wǎng)站服務(wù)封裝成一系列API（Application Programming Interface井佑，應(yīng)用編程接口）開(kāi)放出去妻导，供第三方開(kāi)發(fā)者使用基茵，這種行為就叫做開(kāi)放網(wǎng)站的API椿访，所開(kāi)放的API就被稱作OpenAPI（開(kāi)放API）漓拾。

以前的軟件開(kāi)發(fā)都是針對(duì)特定的用戶或群體進(jìn)行設(shè)計(jì),但用戶的需求是千差萬(wàn)別的,眾口難調(diào)就是這個(gè)道理阁最。隨著軟件開(kāi)發(fā)的發(fā)展,人們的關(guān)注點(diǎn)和設(shè)計(jì)模式也在悄悄發(fā)生著變化,我與其針對(duì)特定客戶進(jìn)行開(kāi)發(fā),不如站在大眾的角度進(jìn)行設(shè)計(jì),把自己從甲方乙方的魔咒中解禁出來(lái),自己成為甲方。也就是說(shuō)我以前開(kāi)發(fā)的軟件只給你用,你還不滿意,現(xiàn)在我只提供核心業(yè)務(wù),你自己來(lái)對(duì)接,你想設(shè)計(jì)成什么樣子就設(shè)計(jì)成什么樣子骇两。于是 Opean Api 應(yīng)運(yùn)而生Ｋ僦帧！淘寶低千、阿里配阵、騰訊都是這么干的,人家是大公司,規(guī)則的制定者,人家怎么規(guī)定接口,你就得怎么對(duì)接！示血！有一個(gè)網(wǎng)站叫 聚合數(shù)據(jù) 專(zhuān)門(mén)提供一些免費(fèi)的和收費(fèi)的優(yōu)秀 API,有興趣的可以上去注冊(cè)玩玩棋傍。

關(guān)于如何開(kāi)發(fā)這樣的一套接口,刨除實(shí)際的業(yè)務(wù)邏輯不說(shuō),我們來(lái)看看怎么設(shè)計(jì)?下面是我在設(shè)計(jì)的時(shí)候遇到問(wèn)題的思考,可能不全面僅供參考!

先來(lái)看看有那幾點(diǎn)需要考量?我也是憑經(jīng)驗(yàn)和 Google。

簽名鑒權(quán)（我需要知道請(qǐng)求我的是誰(shuí),有沒(méi)有訪問(wèn)這個(gè)接口的權(quán)限）
流量控制（我不可能讓你隨隨便便就無(wú)節(jié)制的訪問(wèn)我,我要能隨時(shí)關(guān)停你）
請(qǐng)求轉(zhuǎn)發(fā)（請(qǐng)求過(guò)來(lái)的 url,需要找到真正的業(yè)務(wù)處理邏輯,api最好只負(fù)責(zé)接口的規(guī)范,不負(fù)責(zé)業(yè)務(wù)的實(shí)現(xiàn)）
日志處理（你可以保持沉默,但你說(shuō)的每一句話都會(huì)成為呈堂供證）
異常處理（即使老子內(nèi)部出了問(wèn)題,你也不會(huì)看到我的異常堆棧信息,我會(huì)告訴你我病了,請(qǐng)稍后再試）
參數(shù)規(guī)范（順我者倡,逆我者亡）
多機(jī)部署（我有九條命）
異步回調(diào)（別想阻塞我,但我可以玩死你）
錯(cuò)誤信息（你要認(rèn)識(shí)到自己錯(cuò)誤）

做API,尤其是 Open API 最重要的就是安全难审、安全瘫拣、安全,試想一下,你的接口我可以隨隨便便就猜對(duì)賬號(hào)密碼,隨隨便便就可以DDOS 你,你都沒(méi)有辦法保證用戶信息的安全,誰(shuí)還敢用你。其實(shí)你是在做一件反黑客的設(shè)計(jì),呵呵,是不是高大尚了很多告喊。

Client:你怎么知道一個(gè)請(qǐng)求是我而不是別人呢?

API:你如果對(duì)接我,我給你起一個(gè)全世界唯一名字就吧,你請(qǐng)求的時(shí)候就告訴我你叫 xxx,賦值到請(qǐng)求中的app_key中就行,至于這個(gè)字段叫app_key還是叫 UserName還是叫 client_id,這個(gè)看你心情了麸拄。于是就有了接口的第一個(gè)功能,給客戶起一個(gè)唯一名字。

Client:如果別人也知道了這個(gè)用戶名,冒充我怎么辦?

API:我還會(huì)給你一個(gè)配套的密碼,密碼只有你我知道,你請(qǐng)求的時(shí)候,把密碼帶過(guò)來(lái),我先驗(yàn)證密碼,密碼通過(guò)了我才允許訪問(wèn)葱绒。這樣就沒(méi)人能冒充的了你了吧感帅。你密碼丟了,那就是你自己的事情了。

Client:現(xiàn)在 HTTP 都是明文通信,我每次訪問(wèn)都帶上我的賬號(hào)密碼,那不等于廣而告之天下嗎?就像拿著一袋子錢(qián)在路上邊走邊喊“快來(lái)?yè)屛已降氐恚】靵?lái)?yè)屛已绞颍　保粋€(gè)小小的嗅探器就能把用戶的密碼拿到手，如果用戶習(xí)慣在所有地方用一個(gè)密碼实苞，那么你闖大禍了豺撑，黑客通過(guò)撞庫(kù)的方法能把用戶的所有信息一鍋端。

API:那就就用你的賬號(hào)密碼先到我這兒換取一個(gè)口令吧,我們叫 token,這樣攜帶口令且口令正確的我們就認(rèn),沒(méi)有攜帶口令或口令不正確的我們幾回絕,這樣你就不用帶著密碼滿世界跑了黔牵。

Client:但是那如果 Token 被截獲了呢聪轿？黑客重放怎么辦！猾浦！

API:這個(gè)口令是有一個(gè)過(guò)期時(shí)間的比如10分鐘陆错、一個(gè)小時(shí)、一天金赦、3個(gè)月等等,你們也可以做到單點(diǎn)登錄,我這邊也可以有效的控制外人的入侵,同時(shí)避免了重復(fù)信息的反復(fù)查詢數(shù)據(jù)庫(kù)和對(duì)比等操作,絕對(duì)可以提高響應(yīng)速度,校驗(yàn) token 的有效性花費(fèi)的時(shí)間絕對(duì)比查數(shù)據(jù)庫(kù)要來(lái)的快啊音瓷。我們?cè)诜?wù)器端接口被調(diào)用時(shí)就可以對(duì)發(fā)起請(qǐng)求的ip地址、user-agent之類(lèi)的信息作比對(duì)夹抗，以防止偽造绳慎。再然后，如果token的有效期設(shè)得小漠烧，過(guò)一會(huì)兒它就過(guò)期了杏愤，除非黑客可以持續(xù)截獲你的token，否則他只能干瞪眼已脓。

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

API:那就上 HTTPS ,密碼什么的用 SSL 加密協(xié)議傳輸,我看誰(shuí)還能竊取到呢?你要還糾結(jié)呢咱就上非對(duì)稱?

Client:…

API:還有話說(shuō)么?沒(méi)話說(shuō)就老老實(shí)實(shí)對(duì)接

網(wǎng)絡(luò)攻防

CORS
CSRF
劫持攻擊
DDOS
XSS
SQL注入
文件上傳漏洞
緩沖區(qū)溢出

如何設(shè)計(jì)一個(gè)符合 RESTful 的 OpenAPI

協(xié)議

API 與用戶的通信協(xié)議珊楼，建議使用 HTTPs 協(xié)議。

域名

應(yīng)該盡量將 API 部署在專(zhuān)用域名之下摆舟。

https://api.example.com

如果確定 API 很簡(jiǎn)單亥曹，不會(huì)有進(jìn)一步擴(kuò)展邓了，可以考慮放在主域名下恨诱。

https://example.org/api/

版本（Versioning）

應(yīng)該將 API 的版本號(hào)放入U(xiǎn)RL。

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

另一種做法是骗炉，將版本號(hào)放在 HTTP 頭信息中照宝，但不如放入 URL 方便和直觀。Github 采用這種做法句葵。

路徑（Endpoint）

路徑又稱"終點(diǎn)"（endpoint）厕鹃，表示 API 的具體網(wǎng)址。

在 RESTful 架構(gòu)中乍丈，每個(gè)網(wǎng)址代表一種資源（resource）剂碴，所以網(wǎng)址中不能有動(dòng)詞，只能有名詞轻专，而且所用的名詞往往與數(shù)據(jù)庫(kù)的表格名對(duì)應(yīng)忆矛。一般來(lái)說(shuō)，數(shù)據(jù)庫(kù)中的表都是同種記錄的"集合"（collection），所以 API 中的名詞也應(yīng)該使用復(fù)數(shù)催训。

舉例來(lái)說(shuō)洽议，有一個(gè) API 提供動(dòng)物園（zoo）的信息，還包括各種動(dòng)物和雇員的信息漫拭，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣亚兄。

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

HTTP 動(dòng)詞

對(duì)于資源的具體操作類(lèi)型，由 HTTP 動(dòng)詞表示采驻。

常用的HTTP動(dòng)詞有下面五個(gè)（括號(hào)里是對(duì)應(yīng)的SQL命令）审胚。

GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）。
POST（INSERT）：在服務(wù)器新建一個(gè)資源礼旅。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）菲盾。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。
DELETE（DELETE）：從服務(wù)器刪除資源各淀。

還有兩個(gè)不常用的 HTTP 動(dòng)詞懒鉴。

HEAD：獲取資源的元數(shù)據(jù)。

OPTIONS：獲取信息碎浇，關(guān)于資源的哪些屬性是客戶端可以改變的临谱。

下面是一些例子。

GET /zoos：列出所有動(dòng)物園
POST /zoos：新建一個(gè)動(dòng)物園
GET /zoos/ID：獲取某個(gè)指定動(dòng)物園的信息
PUT /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的全部信息）
PATCH /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的部分信息）
DELETE /zoos/ID：刪除某個(gè)動(dòng)物園
GET /zoos/ID/animals：列出某個(gè)指定動(dòng)物園的所有動(dòng)物
DELETE /zoos/ID/animals/ID：刪除某個(gè)指定動(dòng)物園的指定動(dòng)物

過(guò)濾信息（Filtering）

如果記錄數(shù)量很多奴璃，服務(wù)器不可能都將它們返回給用戶悉默。API應(yīng)該提供參數(shù)，過(guò)濾返回結(jié)果苟穆。

下面是一些常見(jiàn)的參數(shù)抄课。

?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開(kāi)始位置。
?page=2&per_page=100：指定第幾頁(yè)雳旅，以及每頁(yè)的記錄數(shù)跟磨。
?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序攒盈。
?animal_type_id=1：指定篩選條件

參數(shù)的設(shè)計(jì)允許存在冗余抵拘，即允許API路徑和URL參數(shù)偶爾有重復(fù)。比如型豁，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的僵蛛。

狀態(tài)碼（Status Codes）

服務(wù)器向用戶返回的狀態(tài)碼和提示信息，常見(jiàn)的有以下一些（方括號(hào)中是該狀態(tài)碼對(duì)應(yīng)的 HTTP 動(dòng)詞）迎变。

200 OK - [GET]：服務(wù)器成功返回用戶請(qǐng)求的數(shù)據(jù)充尉，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功衣形。
202 Accepted - [*]：表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功驼侠。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請(qǐng)求有錯(cuò)誤，服務(wù)器沒(méi)有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的泪电。
401 Unauthorized - [*]：表示用戶沒(méi)有權(quán)限（令牌般妙、用戶名、密碼錯(cuò)誤）相速。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯(cuò)誤相對(duì)）碟渺，但是訪問(wèn)是被禁止的。
404 NOT FOUND - [*]：用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄突诬，服務(wù)器沒(méi)有進(jìn)行操作苫拍，該操作是冪等的。
406 Not Acceptable - [GET]：用戶請(qǐng)求的格式不可得（比如用戶請(qǐng)求JSON格式旺隙，但是只有XML格式）绒极。
410 Gone -[GET]：用戶請(qǐng)求的資源被永久刪除，且不會(huì)再得到的蔬捷。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)垄提，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯(cuò)誤周拐，用戶將無(wú)法判斷發(fā)出的請(qǐng)求是否成功铡俐。

狀態(tài)碼的完全列表參見(jiàn)這里。

錯(cuò)誤處理（Error handling）

如果狀態(tài)碼是4xx妥粟，就應(yīng)該向用戶返回出錯(cuò)信息审丘。一般來(lái)說(shuō)，返回的信息中將error作為鍵名勾给，出錯(cuò)信息作為鍵值即可滩报。

{
    error: "Invalid API key"
}

返回結(jié)果

針對(duì)不同操作，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范播急。

GET /collection：返回資源對(duì)象的列表（數(shù)組）
GET /collection/resource：返回單個(gè)資源對(duì)象
POST /collection：返回新生成的資源對(duì)象
PUT /collection/resource：返回完整的資源對(duì)象
PATCH /collection/resource：返回完整的資源對(duì)象
DELETE /collection/resource：返回一個(gè)空文檔

Hypermedia API

RESTful API 最好做到 Hypermedia脓钾，即返回結(jié)果中提供鏈接，連向其他 API 方法旅择，使得用戶不查文檔惭笑，也知道下一步應(yīng)該做什么侣姆。

比如生真，當(dāng)用戶向 api.example.com 的根目錄發(fā)出請(qǐng)求，會(huì)得到這樣一個(gè)文檔捺宗。

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

上面代碼表示柱蟀，文檔中有一個(gè)link屬性，用戶讀取這個(gè)屬性就知道下一步該調(diào)用什么API了蚜厉。

rel 表示這個(gè) API 與當(dāng)前網(wǎng)址的關(guān)系（collection 關(guān)系长已，并給出該 collection 的網(wǎng)址），href 表示 API 的路徑，title 表示 API 的標(biāo)題术瓮，type 表示返回類(lèi)型康聂。

Hypermedia API 的設(shè)計(jì)被稱為 HATEOAS。Github 的 API 就是這種設(shè)計(jì)胞四，訪問(wèn)api.github.com會(huì)得到一個(gè)所有可用API的網(wǎng)址列表恬汁。

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

從上面可以看到，如果想獲取當(dāng)前用戶的信息辜伟，應(yīng)該去訪問(wèn)api.github.com/user氓侧，然后就得到了下面結(jié)果。

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

上面代碼表示导狡，服務(wù)器給出了提示信息约巷，以及文檔的網(wǎng)址。