API介面設計之RESTful軟體架構風格

說到API介面設計有的喜歡用Web Service，有的喜歡用WCF，當然也有還在用最原始的ashx，aspx頁面的。無論採用什麼方式能很好的滿足業務需求就ok，但是不同的方式在擴充套件性、易用性，可維護性都有一定的差別。如今移動移動網際網路正如火如荼，各種終端，各種平臺，各種開發語言也是層出不窮，所以要設計出能滿足這些要求的API也就顯得至關重要了。

在介紹RESTful前我們來談談API設計要注意的地方：

1、API設計的基本要求

網上的很多關於API設計的觀點都十分”學院派“，它們也許更有理論基礎，但是有時卻和現實世界脫軌（因此我是 自由派）。所以我這篇文章的目標是從實踐的角度出發，給出當前網路應用的API設計最佳實踐（當然，是我認為的最佳了~），如果覺得不合適，我不會遵從標 準。當然作為設計的基礎，幾個必須的原則還是要遵守的：

當標準合理的時候遵守標準。

1. API應該對程式設計師友好，並且在瀏覽器位址列容易輸入。
2. API應該簡單，直觀，容易使用的同時優雅。
3. API應該具有足夠的靈活性來支援上層ui。
4. API設計權衡上述幾個原則。

需要強調的是：API的就是程式設計師的UI，和其他UI一樣，你必須仔細考慮它的使用者體驗！

2、永遠使用SSL

毫無例外，永遠都要使用SSL。你的應用不知道要被誰，以及什麼情況訪問。有些是安全的，有些不是。使用SSL可以減少鑑權的成本：你只需要一個簡單的令牌（token）就可以鑑權了，而不是每次讓使用者對每次請求籤名。

值得注意的是：不要讓非SSL的url訪問重定向到SSL的url。

3、限制API返回值的域

有時候API使用者不需要所有的結果，在進行橫向限制的時候（例如值返回API結果的前十項）還應該可以進行縱向限制。並且這個功能能有效的提高網路頻寬使用率和速度。可以使用fields查詢引數來限制返回的域例如：
GET /ticketsfields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

4、更新和建立操作應該返回資源

PUT、POST、PATCH 操作在對資源進行操作的時候常常有一些副作用：例如created_at,updated_at 時間戳。為了防止使用者多次的API呼叫（為了進行此次的更新操作），我們應該會返回更新的資源（updated representation.）例如：在POST操作以後，返回201 created 狀態碼，並且包含一個指向新資源的url作為返回頭

5、鑑權 Authentication

restful API是無狀態的也就是說使用者請求的鑑權和cookie以及session無關，每一次請求都應該包含鑑權證明。

通過使用ssl我們可以不用每次都提供使用者名稱和密碼：我們可以給使用者返回一個隨機產生的token。這樣可以極大的方便使用瀏覽器訪問API的用 戶。這種方法適用於使用者可以首先通過一次使用者名稱-密碼的驗證並得到token，並且可以拷貝返回的token到以後的請求中。如果不方便，可以使用 OAuth 2來進行token的安全傳輸。

支援jsonp的API需要額外的鑑權方法，因為jsonp請求無法傳送普通的credential。這種情況下可以在查詢url中新增參 數：access_token。注意使用url引數的問題是：目前大部分的網路伺服器都會將query引數儲存到伺服器日誌中，這可能會成為大的安全風 險。

注意上面說到的只是三種傳輸token的方法，實際傳輸的token可能是一樣的。

RESTful軟體架構風格的介面最近很火，也深受API介面開發人員的青睞。雖然前面我說沒有一個萬能的API設計標準。但確實有一個被普遍承認和遵守：RESTfu設計原則。它被Roy Felding提出（在他的”基於網路的軟體架構“論文中第五章）。而REST的核心原則是將你的API拆分為邏輯上的資源。這些資源通過http被操作（GET ,POST,PUT,DELETE）。

今天我就來詳細介紹一下什麼是RESTful軟體架構風格。

百度百科是這樣介紹RESTful的：

REST（英文：Representational State Transfer，簡稱REST）描述了一個架構樣式的網路系統，比如 web 應用程式。它首次出現在 2000 年 Roy Fielding 的博士論文中，他是 HTTP 規範的主要編寫者之一。在目前主流的三種Web服務互動方案中，REST相比於SOAP（Simple Object Access protocol，簡單物件訪問協議）以及XML-RPC更加簡單明瞭，無論是對URL的處理還是對Payload的編碼，REST都傾向於用更加簡單輕量的方法設計和實現。值得注意的是REST並沒有一個明確的標準，而更像是一種設計的風格。
REST 指的是一組架構約束條件和原則。滿足這些約束條件和原則的應用程式或設計就是 RESTful。

Web 應用程式最重要的 REST 原則是，客戶端和伺服器之間的互動在請求之間是無狀態的。從客戶端到伺服器的每個請求都必須包含理解請求所必需的資訊。如果伺服器在請求之間的任何時間點重啟，客戶端不會得到通知。此外，無狀態請求可以由任何可用伺服器回答，這十分適合雲端計算之類的環境。客戶端可以快取資料以改進效能。

在伺服器端，應用程式狀態和功能可以分為各種資源。資源是一個有趣的概念實體，它向客戶端公開。資源的例子有：應用程式物件、資料庫記錄、演算法等等。每個資源都使用 URI (Universal Resource Identifier) 得到一個唯一的地址。所有資源都共享統一的介面，以便在客戶端和伺服器之間傳輸狀態。使用的是標準的 HTTP 方法，比如 GET、PUT、POST 和 DELETE。Hypermedia 是應用程式狀態的引擎，資源表示通過超連結互聯。
由於輕量級以及通過 HTTP 直接傳輸資料的特性，Web 服務的 RESTful 方法已經成為最常見的替代方法。可以使用各種語言（比如 Java 程式、Perl、Ruby、Python、PHP 和 Javascript[包括 Ajax]）實現客戶端。RESTful Web 服務通常可以通過自動客戶端或代表使用者的應用程式訪問。但是，這種服務的簡便性讓使用者能夠與之直接互動，使用它們的 Web 瀏覽器構建一個 GET URL 並讀取返回的內容。

在 REST 樣式的 Web 服務中，每個資源都有一個地址。資源本身都是方法呼叫的目標，方法列表對所有資源都是一樣的。這些方法都是標準方法，包括 HTTP GET、POST、PUT、DELETE，還可能包括 HEADER 和 OPTIONS。
REST 描述了一個架構樣式的互聯絡統（如 Web 應用程式）。REST 約束條件作為一個整體應用時，將生成一個簡單、可擴充套件、有效、安全、可靠的架構。由於它簡便、輕量級以及通過 HTTP 直接傳輸資料的特性，RESTful Web 服務成為基於 SOAP 服務的一個最有前途的替代方案。用於 web 服務和動態 Web 應用程式的多層架構可以實現可重用性、簡單性、可擴充套件性和元件可響應性的清晰分離。開發人員可以輕鬆使用 Ajax 和 RESTful Web 服務一起建立豐富的介面。