電子發(fā)燒友App
API的四種類型
API 同時也是一種中間件，為各種不同平臺提供數(shù)據(jù)共享。根據(jù)單個或分布式平臺上不同軟件應(yīng)用程序間的數(shù)據(jù)共享性能，可以將 API 分為四種類型：
遠程過程調(diào)用（RPC）：通過作用在共享數(shù)據(jù)緩存器上的過程（或任務(wù)）實現(xiàn)程序間的通信。
標準查詢語言（SQL）：是標準的訪問數(shù)據(jù)的查詢語言，通過通用數(shù)據(jù)庫實現(xiàn)應(yīng)用程序間的數(shù)據(jù)共享。
文件傳輸：文件傳輸通過發(fā)送格式化文件實現(xiàn)應(yīng)用程序間數(shù)據(jù)共享。
信息交付：指松耦合或緊耦合應(yīng)用程序間的小型格式化信息，通過程序間的直接通信實現(xiàn)數(shù)據(jù)共享。
當前應(yīng)用于 API 的標準包括 ANSI 標準 SQL API。另外還有一些應(yīng)用于其它類型的標準尚在制定之中。API 可以應(yīng)用于所有計算機平臺和操作系統(tǒng)。這些 API 以不同的格式連接數(shù)據(jù)（如共享數(shù)據(jù)緩存器、數(shù)據(jù)庫結(jié)構(gòu)、文件框架）。每種數(shù)據(jù)格式要求以不同的數(shù)據(jù)命令和參數(shù)實現(xiàn)正確的數(shù)據(jù)通信，但同時也會產(chǎn)生不同類型的錯誤。因此，除了具備執(zhí)行數(shù)據(jù)共享任務(wù)所需的知識以外，這些類型的 API 還必須解決很多網(wǎng)絡(luò)參數(shù)問題和可能的差錯條件，即每個應(yīng)用程序都必須清楚自身是否有強大的性能支持程序間通信。相反由于這種 API 只處理一種信息格式，所以該情形下的信息交付 API 只提供較小的命令、網(wǎng)絡(luò)參數(shù)以及差錯條件子集。正因為如此，交付 API 方式大大降低了系統(tǒng)復(fù)雜性，所以當應(yīng)用程序需要通過多個平臺實現(xiàn)數(shù)據(jù)共享時，采用信息交付 API 類型是比較理想的選擇。
API 與圖形用戶接口（GUI）或命令接口有著鮮明的差別：API 接口屬于一種操作系統(tǒng)或程序接口，而后兩者都屬于直接用戶接口。
有時公司會將 API 作為其公共開放系統(tǒng)。也就是說，公司制定自己的系統(tǒng)接口標準，當需要執(zhí)行系統(tǒng)整合、自定義和程序應(yīng)用等操作時，公司所有成員都可以通過該接口標準調(diào)用源代碼，該接口標準被稱之為開放式 API。? ? ? ?
?API設(shè)計
背景
目前互聯(lián)網(wǎng)上充斥著大量的關(guān)于RESTful API（為方便，下文中“RESTful API ”簡寫為“API”）如何設(shè)計的文章，然而卻沒有一個”萬能“的設(shè)計標準：如何鑒權(quán)？API 格式如何？你的API是否應(yīng)該加入版本信息？當你開始寫一個app的時候，特別是后端模型部分已經(jīng)寫完的時候，你不得不殫精竭慮的設(shè)計和實現(xiàn)自己app的public API部分。因為一旦發(fā)布，對外發(fā)布的API將會很難改變。
在給SupportedFu設(shè)計API的時候，我試圖以實用的角度來解決上面提到的問題。我希望可以設(shè)計出容易使用，容易部署，并且足夠靈活的API，本文因此而生。
API設(shè)計的基本要求
網(wǎng)上的很多關(guān)于API設(shè)計的觀點都十分”學(xué)院派“，它們也許更有理論基礎(chǔ)，但是有時卻和現(xiàn)實世界脫軌（因此我是自由派）。所以我這篇文章的目標是從實踐的角度出發(fā)，給出當前網(wǎng)絡(luò)應(yīng)用的API設(shè)計最佳實踐（當然，是我認為的最佳了~），如果覺得不合適，我不會遵從標準。當然作為設(shè)計的基礎(chǔ)，幾個必須的原則還是要遵守的：
當標準合理的時候遵守標準。
API應(yīng)該對程序員友好，并且在瀏覽器地址欄容易輸入。
API應(yīng)該簡單，直觀，容易使用的同時優(yōu)雅。
API應(yīng)該具有足夠的靈活性來支持上層ui。
API設(shè)計權(quán)衡上述幾個原則。
需要強調(diào)的是：API的就是程序員的UI，和其他UI一樣，你必須仔細考慮它的用戶體驗！
雖然前面我說沒有一個萬能的API設(shè)計標準。但確實有一個被普遍承認和遵守：RESTfu設(shè)計原則。它被Roy Felding提出（在他的”基于網(wǎng)絡(luò)的軟件架構(gòu)“論文中第五章）。而REST的核心原則是將你的API拆分為邏輯上的資源。這些資源通過http被操作（GET ，POST，PUT，DELETE）。
那么我應(yīng)該如何拆分出這些資源呢？
顯然從API用戶的角度來看，”資源“應(yīng)該是個名詞。即使你的內(nèi)部數(shù)據(jù)模型和資源已經(jīng)有了很好的對應(yīng)，API設(shè)計的時候你仍然不需要把它們一對一的都暴露出來。這里的關(guān)鍵是隱藏內(nèi)部資源，暴露必需的外部資源。
在SupportFu里，資源是 ticket、user、group。
一旦定義好了要暴露的資源，你可以定義資源上允許的操作，以及這些操作和你的API的對應(yīng)關(guān)系：
GET /tickets # 獲取ticket列表
GET /tickets/12 # 查看某個具體的ticket
POST /tickets # 新建一個ticket
PUT /tickets/12 # 更新ticket 12.
DELETE /tickets/12 #刪除ticekt 12
可以看出使用REST的好處在于可以充分利用http的強大實現(xiàn)對資源的CURD功能。而這里你只需要一個endpoint：/tickets，再沒有其他什么命名規(guī)則和url規(guī)則了，cool！
這個endpoint的單數(shù)復(fù)數(shù)
一個可以遵從的規(guī)則是：雖然看起來使用復(fù)數(shù)來描述某一個資源實例看起來別扭，但是統(tǒng)一所有的endpoint，使用復(fù)數(shù)使得你的URL更加規(guī)整。這讓API使用者更加容易理解，對開發(fā)者來說也更容易實現(xiàn)。
如何處理關(guān)聯(lián)？關(guān)于如何處理資源之間的管理REST原則也有相關(guān)的描述：
GET /tickets/12/messages- Retrieves list of messages for ticket #12
GET /tickets/12/messages/5- Retrieves message #5 for ticket #12
POST /tickets/12/messages- Creates a new message in ticket #12
PUT /tickets/12/messages/5- Updates message #5 for ticket #12
PATCH /tickets/12/messages/5- Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5- Deletes message #5 for ticket #12
其中，如果這種關(guān)聯(lián)和資源獨立，那么我們可以在資源的輸出表示中保存相應(yīng)資源的endpoint。然后API的使用者就可以通過點擊鏈接找到相關(guān)的資源。如果關(guān)聯(lián)和資源聯(lián)系緊密。資源的輸出表示就應(yīng)該直接保存相應(yīng)資源信息。（例如這里如果message資源是獨立存在的，那么上面 GET /tickets/12/messages就會返回相應(yīng)message的鏈接；相反的如果message不獨立存在，他和ticket依附存在，則上面的API調(diào)用返回直接返回message信息）
不符合CURD的操作
對這個令人困惑的問題，下面是一些解決方法：
重構(gòu)你的行為action。當你的行為不需要參數(shù)的時候，你可以把active對應(yīng)到activated這個資源，（更新使用patch）。
以子資源對待。例如：github上，對一個gists加星操作：PUT /gists/：id/star 并且取消星操作：DELETE /gists/：id/star.
有時候action實在沒有難以和某個資源對應(yīng)上例如search。那就這么辦吧。我認為API的使用者對于/search這種url也不會有太大意見的（畢竟他很容易理解）。只要注意在文檔中寫清楚就可以了。
#e#
永遠使用SSL
毫無例外，永遠都要使用SSL。你的應(yīng)用不知道要被誰，以及什么情況訪問。有些是安全的，有些不是。使用SSL可以減少鑒權(quán)的成本：你只需要一個簡單的令牌（token）就可以鑒權(quán)了，而不是每次讓用戶對每次請求簽名。
值得注意的是：不要讓非SSL的url訪問重定向到SSL的url。
文檔
文檔和API本身一樣重要。文檔應(yīng)該容易找到，并且公開（把它們藏到pdf里面或者存到需要登錄的地方都不太好）。文檔應(yīng)該有展示請求和輸出的例子：或者以點擊鏈接的方式或者通過curl的方式（請見openstack的文檔）。如果有更新（特別是公開的API），應(yīng)該及時更新文檔。文檔中應(yīng)該有關(guān)于何時棄用某個API的時間表以及詳情。使用郵件列表或者博客記錄是好方法。
版本化
在API上加入版本信息可以有效的防止用戶訪問已經(jīng)更新了的API，同時也能讓不同主要版本之間平穩(wěn)過渡。關(guān)于是否將版本信息放入url還是放入請求頭有過爭論：API version should be included in the URL or in a header. 學(xué)術(shù)界說它應(yīng)該放到header里面去，但是如果放到url里面我們就可以跨版本的訪問資源了。。（參考openstack）。
strip使用的方法就很好：它的url里面有主版本信息，同時請求頭倆面有子版本信息。這樣在子版本變化過程中url的穩(wěn)定的。變化有時是不可避免的，關(guān)鍵是如何管理變化。完整的文檔和合理的時間表都會使得API使用者使用的更加輕松。
結(jié)果過濾，排序，搜索：
url最好越簡短越好，和結(jié)果過濾，排序，搜索相關(guān)的功能都應(yīng)該通過參數(shù)實現(xiàn)（并且也很容易實現(xiàn)）。
過濾：為所有提供過濾功能的接口提供統(tǒng)一的參數(shù)。例如：你想限制get /tickets 的返回結(jié)果：只返回那些open狀態(tài)的ticket–get /tickektsstate=open這里的state就是過濾參數(shù)。
排序：和過濾一樣，一個好的排序參數(shù)應(yīng)該能夠描述排序規(guī)則，而不業(yè)務(wù)相關(guān)。復(fù)雜的排序規(guī)則應(yīng)該通過組合實現(xiàn)：
GET /ticketssort=-priority- Retrieves a list of tickets in descending order of priority
GET /ticketssort=-priority，created_at- Retrieves a list of tickets in descending order of priority. Within a specific priority， older tickets are ordered first
這里第二條查詢中，排序規(guī)則有多個rule以逗號間隔組合而成。
搜索：有些時候簡單的排序是不夠的。我們可以使用搜索技術(shù)（ElasticSearch和Lucene）來實現(xiàn)（依舊可以作為url的參數(shù)）。
GET /ticketsq=return&state=open&sort=-priority，created_at- Retrieve the highest priority open tickets mentioning the word ‘return’
對于經(jīng)常使用的搜索查詢，我們可以為他們設(shè)立別名，這樣會讓API更加優(yōu)雅。例如：
get /ticketsq=recently_closed -》 get /tickets/recently_closed.
限制API返回值的域
有時候API使用者不需要所有的結(jié)果，在進行橫向限制的時候（例如值返回API結(jié)果的前十項）還應(yīng)該可以進行縱向限制。并且這個功能能有效的提高網(wǎng)絡(luò)帶寬使用率和速度。可以使用fields查詢參數(shù)來限制返回的域例如：
GET /ticketsfields=id，subject，customer_name，updated_at&state=open&sort=-updated_at
更新和創(chuàng)建操作應(yīng)該返回資源
PUT、POST、PATCH 操作在對資源進行操作的時候常常有一些副作用：例如created_at，updated_at 時間戳。為了防止用戶多次的API調(diào)用（為了進行此次的更新操作），我們應(yīng)該會返回更新的資源（updated representation.）例如：在POST操作以后，返回201 created 狀態(tài)碼，并且包含一個指向新資源的url作為返回頭
是否需要 “HATEOAS“
網(wǎng)上關(guān)于是否允許用戶創(chuàng)建新的url有很大的異議（注意不是創(chuàng)建資源產(chǎn)生的url）。為此REST制定了HATEOAS來描述了和endpoint進行交互的時候，行為應(yīng)該在資源的metadata返回值里面進行定義。
（譯注：作者這里認為HATEOAS還不算成熟，我也不怎么理解這段就算了，讀者感興趣可以自己去原文查看）
只提供json作為返回格式
現(xiàn)在開始比較一下XML和json了。XML即冗長，難以閱讀，又不適合各種編程語言解析。當然XML有擴展性的優(yōu)勢，但是如果你只是將它來對內(nèi)部資源串行化，那么他的擴展優(yōu)勢也發(fā)揮不出來。很多應(yīng)用（youtube，twitter，box）都已經(jīng)開始拋棄XML了，我也不想多費口舌。給了google上的趨勢圖吧：
當然如果的你使用用戶里面企業(yè)用戶居多，那么可能需要支持XML。如果是這樣的話你還有另外一個問題：你的http請求中的media類型是應(yīng)該和accept 頭同步還是和url？為了方便（browser explorability），應(yīng)該是在url中（用戶只要自己拼url就好了）。如果這樣的話最好的方法是使用.xml或者.json的后綴。
命名方式？
是蛇形命令（下劃線和小寫）還是駝峰命名？如果使用json那么最好的應(yīng)該是遵守JAVASCRIPT的命名方法-也就是說駱駝命名法。如果你正在使用多種語言寫一個庫，那么最好按照那些語言所推薦的，java，c#使用駱駝，python，ruby使用snake。
個人意見：我總覺得蛇形命令更好使一些，當然這沒有什么理論的依據(jù)。有人說蛇形命名讀起來更快，能達到20%，也不知道真假http://ieeexplore.ieee.org/xpl/articleDetails.jsptp=&arnumber=5521745
默認使用pretty print格式，使用gzip
只是使用空格的返回結(jié)果從瀏覽器上看總是覺得很惡心（一大坨有沒有？～）。當然你可以提供url上的參數(shù)來控制使用“pretty print”，但是默認開啟這個選項還是更加友好。格外的傳輸上的損失不會太大。相反你如果忘了使用gzip那么傳輸效率將會大大減少，損失大大增加。想象一個用戶正在debug那么默認的輸出就是可讀的-而不用將結(jié)果拷貝到其他什么軟件中在格式化-是想起來就很爽的事，不是么？
下面是一個例子：
$ curl https://API.github.com/users/veesahni 》 with-whitespace.txt
$ ruby -r json -e ‘puts JSON JSON.parse（STDIN.read）’ 《 with-whitespace.txt 》 without-whitespace.txt
$ gzip -c with-whitespace.txt 》 with-whitespace.txt.gz
$ gzip -c without-whitespace.txt 》 without-whitespace.txt.gz
輸出如下：
without-whitespace.txt- 1252 bytes
with-whitespace.txt- 1369 bytes
without-whitespace.txt.gz- 496 bytes
with-whitespace.txt.gz- 509 bytes
在上面的例子中，多余的空格使得結(jié)果大小多出了8.5%（沒有使用gzip），相反只多出了2.6%。據(jù)說：twitter使用gzip之后它的streaming API傳輸減少了80%（link:https://dev.twitter.com/blog/announcing-gzip-compression-streaming-APIs）。
只在需要的時候使用“envelope”
很多API象下面這樣返回結(jié)果：
{
“data” ： {
“id” ： 123，
“name” ： “John”
}
}
理由很簡單：這樣做可以很容易擴展返回結(jié)果，你可以加入一些分頁信息，一些數(shù)據(jù)的元信息等－這對于那些不容易訪問到返回頭的API使用者來說確實有用，但是隨著“標準”的發(fā)展（cors和http://tools.ietf.org/html/rfc5988#page-6都開始被加入到標準中了），我個人推薦不要那么做。
何時使用envelope？
有兩種情況是應(yīng)該使用envelope的。如果API使用者確實無法訪問返回頭，或者API需要支持交叉域請求（通過jsonp）。
jsonp請求在請求的url中包含了一個callback函數(shù)參數(shù)。如果給出了這個參數(shù)，那么API應(yīng)該返回200，并且把真正的狀態(tài)碼放到返回值里面（包裝在信封里），例如：
callback_function（{
status_code： 200，
next_page： “https://。.”，
response： {
... actual JSON response body 。..
}
}）
同樣為了支持無法方法返回頭的API使用者，可以允許envelope=true這樣的參數(shù)。
在post，put，patch上使用json作為輸入
如果你認同我上面說的，那么你應(yīng)該決定使用json作為所有的API輸出格式，那么我們接下來考慮考慮API的輸入數(shù)據(jù)格式。
很多的API使用url編碼格式：就像是url查詢參數(shù)的格式一樣：單純的鍵值對。這種方法簡單有效，但是也有自己的問題：它沒有數(shù)據(jù)類型的概念。這使得程序不得不根據(jù)字符串解析出布爾和整數(shù)，而且還沒有層次結(jié)構(gòu)–雖然有一些關(guān)于層次結(jié)構(gòu)信息的約定存在可是和本身就支持層次結(jié)構(gòu)的json比較一下還是不很好用。
當然如果API本身就很簡單，那么使用url格式的輸入沒什么問題。但對于復(fù)雜的API你應(yīng)該使用json?；蛘吒纱嘟y(tǒng)一使用json。
注意使用json傳輸?shù)臅r候，要求請求頭里面加入：Content-Type：application/json.，否則拋出415異常（unsupported media type）。
分頁
分頁數(shù)據(jù)可以放到“信封”里面，但隨著標準的改進，現(xiàn)在我推薦將分頁信息放到link header里面：http://tools.ietf.org/html/rfc5988#page-6。
使用link header的API應(yīng)該返回一系列組合好了的url而不是讓用戶自己再去拼。這點在基于游標的分頁中尤為重要。例如下面，來自github的文檔
Link： 《https://api.github.com/user/repos？page=3&per_page=100》; rel=“next”，
《https://api.github.com/user/repos？page=50&per_page=100》; rel=“l(fā)ast”
自動加載相關(guān)的資源
很多時候，自動加載相關(guān)資源非常有用，可以很大的提高效率。但是這卻和RESTful的原則相背。為了如此，我們可以在url中添加參數(shù)：embed（或者expend）。embed可以是一個逗號分隔的串，例如：
GET /ticket/12embed=customer.name，assigned_user
對應(yīng)的API返回值如下：
{
“id” ： 12，
“subject” ： “I have a question！”，
“summary” ： “Hi， 。..?！?，
“customer” ： {
“name” ： “Bob”
}，
assigned_user： {
“id” ： 42，
“name” ： “Jim”，
}
}
值得提醒的是，這個功能有時候會很復(fù)雜，并且可能導(dǎo)致N+1 SELECT 問題。
重寫HTTP方法
有的客戶端只能發(fā)出簡單的GET 和POST請求。為了照顧他們，我們可以重寫HTTP請求。這里沒有什么標準，但是一個普遍的方式是接受X-HTTP-Method-Override請求頭。
速度限制
為了避免請求泛濫，給API設(shè)置速度限制很重要。為此 RFC 6585 引入了HTTP狀態(tài)碼429（too many requests）。加入速度設(shè)置之后，應(yīng)該提示用戶，至于如何提示標準上沒有說明，不過流行的方法是使用HTTP的返回頭。
下面是幾個必須的返回頭（依照twitter的命名規(guī)則）：
X-Rate-Limit-Limit ：當前時間段允許的并發(fā)請求數(shù)
X-Rate-Limit-Remaining：當前時間段保留的請求數(shù)。
X-Rate-Limit-Reset：當前時間段剩余秒數(shù)
為什么使用當前時間段剩余秒數(shù)而不是時間戳？
時間戳保存的信息很多，但是也包含了很多不必要的信息，用戶只需要知道還剩幾秒就可以再發(fā)請求了這樣也避免了clock skew問題。
有些API使用UNIX格式時間戳，我建議不要那么干。為什么？HTTP 已經(jīng)規(guī)定了使用 RFC 1123 時間格式
鑒權(quán) Authentication
restful API是無狀態(tài)的也就是說用戶請求的鑒權(quán)和cookie以及session無關(guān)，每一次請求都應(yīng)該包含鑒權(quán)證明。
通過使用ssl我們可以不用每次都提供用戶名和密碼：我們可以給用戶返回一個隨機產(chǎn)生的token。這樣可以極大的方便使用瀏覽器訪問API的用戶。這種方法適用于用戶可以首先通過一次用戶名-密碼的驗證并得到token，并且可以拷貝返回的token到以后的請求中。如果不方便，可以使用OAuth 2來進行token的安全傳輸。
支持jsonp的API需要額外的鑒權(quán)方法，因為jsonp請求無法發(fā)送普通的credential。這種情況下可以在查詢url中添加參數(shù)：access_token。注意使用url參數(shù)的問題是：目前大部分的網(wǎng)絡(luò)服務(wù)器都會講query參數(shù)保存到服務(wù)器日志中，這可能會成為大的安全風險。
注意上面說到的只是三種傳輸token的方法，實際傳輸?shù)膖oken可能是一樣的。
緩存
HTTP提供了自帶的緩存框架。你需要做的是在返回的時候加入一些返回頭信息，在接受輸入的時候加入輸入驗證?；緝煞N方法：
ETag：當生成請求的時候，在HTTP頭里面加入ETag，其中包含請求的校驗和和哈希值，這個值和在輸入變化的時候也應(yīng)該變化。如果輸入的HTTP請求包含IF-NONE-MATCH頭以及一個ETag值，那么API應(yīng)該返回304 not modified狀態(tài)碼，而不是常規(guī)的輸出結(jié)果。
Last-Modified：和etag一樣，只是多了一個時間戳。返回頭里的Last-Modified：包含了 RFC 1123 時間戳，它和IF-MODIFIED-SINCE一致。HTTP規(guī)范里面有三種date格式，服務(wù)器應(yīng)該都能處理。
出錯處理
就像html錯誤頁面能夠顯示錯誤信息一樣，API 也應(yīng)該能返回可讀的錯誤信息–它應(yīng)該和一般的資源格式一致。API應(yīng)該始終返回相應(yīng)的狀態(tài)碼，以反映服務(wù)器或者請求的狀態(tài)。API的錯誤碼可以分為兩部分，400系列和500系列，400系列表明客戶端錯誤：如錯誤的請求格式等。500系列表示服務(wù)器錯誤。API應(yīng)該至少將所有的400系列的錯誤以json形式返回。如果可能500系列的錯誤也應(yīng)該如此。json格式的錯誤應(yīng)該包含以下信息：一個有用的錯誤信息，一個唯一的錯誤碼，以及任何可能的詳細錯誤描述。如下：
{
“code” ： 1234，
“message” ： “Something bad happened ：-（”，
“description” ： “More details about the error here”
}
對PUT，POST，PATCH的輸入的校驗也應(yīng)該返回相應(yīng)的錯誤信息，例如：
{
“code” ： 1024，
“message” ： “Validation Failed”，
“errors” ： ［
{
“code” ： 5432，
“field” ： “first_name”，
“message” ： “First name cannot have fancy characters”
}，
{
“code” ： 5622，
“field” ： “password”，
“message” ： “Password cannot be blank”
}
］
}
HTTP 狀態(tài)碼
200 ok - 成功返回狀態(tài)，對應(yīng)，GET，PUT，PATCH，DELETE.
201 created - 成功創(chuàng)建。
304 not modified - HTTP緩存有效。
400 bad request - 請求格式錯誤。
401 unauthorized - 未授權(quán)。
403 forbidden - 鑒權(quán)成功，但是該用戶沒有權(quán)限。
404 not found - 請求的資源不存在
405 method not allowed - 該http方法不被允許。
410 gone - 這個url對應(yīng)的資源現(xiàn)在不可用。
415 unsupported media type - 請求類型錯誤。
422 unprocessable entity - 校驗錯誤時用。
429 too many request - 請求過多。
工商網(wǎng)監(jiān)
評論