REST API 最佳入門指南

http://www.javashuo.com/article/p-myhxzlya-mg.html 

若是你看到這裏，你之前可能據說過API 和REST,而後你就會想:「這些都是什麼東西？」。也許你已經瞭解過一些這方面的知識，但殊不知道從何入手。在這個教程中，我將會詮釋REST的基礎以及如何給應用建立一個API（包括認證受權）。

什麼是API?

API是Application Programming Interface（應用程序界面）的縮寫，它是拿來描述一個類庫的特徵或是如何去運用它。你我的收藏的類庫也許包含有可用功能的「API文檔」，那些必需的參數咱們該怎麼稱呼它們？諸如此類等等。

然而，現在不少人蔘考API文檔時，他們經常參考一種可能會經過網絡分享你的應用數據HTTP API，例如，Twitter提供一個API能讓用戶在特定的格式下請求推文，以便用戶方便導入到本身的應用程序中。這就是HTTP API的真正強大之處。它可以從多個應用程序中混搭數據到混合應用程序中，或是建立一個能加強使用他人應用體驗的應用程序。

這樣說吧，好比說咱們有一個能夠容許咱們查看（view），建立（create），編輯（edit）以及刪除（delete）部件的應用程序。咱們能夠建立一個可讓咱們執行這些功能的HTTP API:

當人們開始去實現他們本身的API接口時，問題就出現了。居然沒有一個標準的方法來命名URL，人們老是要參考API才得知它是如何運做的。一個API中可能命名一個URL爲/view_widgets，可是另外一個API可能就命名成/widgets/all.

不用擔憂！REST幫你搞定這些混亂！

什麼是REST呢?

REST是Representational State Transfer的縮寫，它是由羅伊·菲爾丁（Roy Fielding）提出的，是用來描述建立HTTP API的標準方法的，他發現這四種經常使用的行爲（查看（view），建立（create），編輯（edit）和刪除（delete））均可以直接映射到HTTP 中已實現的GET,POST,PUT和DELETE方法。

HTTP 中的8中不一樣的方法：

大多數狀況下，當你在使用你的瀏覽器的點點看看的時候，其實只用到HTTP的GET方法。GET方法是在你向因特網請求資源的時候纔會用到的。當你提交一個表單時，你就會常常用到POST方法來回傳數據到網站上。至於其餘的幾種方法，某些瀏覽器可能根本就沒有去徹底實現它們。可是，若是是供咱們使用的話，就沒什麼問題。問題是咱們有不少要選擇去幫助描述這四大行爲的HTTP方法，咱們將會用到那些已經知道如何去使用這些不一樣的HTTP方法的客戶端類庫。

REST例子

讓咱們來看下幾個讓API表述性狀態轉移化的例子，就用咱們以前說的那幾個部件來解釋：

解剖REST URL

你可能已經注意的前面的幾個例子，REST URL使用着一套一致的命名方法。當你跟API交互時，你幾乎常常操做一些對象。在咱們的例子中，咱們講的是部件。在REST中，咱們稱之爲Resource。URL的第一部分常常是這個資源的複數形式：

/widgets

當咱們參考收集的資源時（list all：列出全部 和add one：新增一個），這將會常常用到。當你用到一些特殊的資源的時候，你就會給URL增長一個id，這個URL在你想要「view」，「edit」和「delete」特殊資源的時候會被使用。

嵌套資源

若是說，咱們的部件有不少用戶使用，URL的結構又將會是怎樣的呢？

嵌套資源在URL裏是徹底兼容的，可是超過兩層嵌套就不是很好的方法了。其實這根本不須要，由於你徹底能夠以ID的形式參考到那些嵌套資源，總比嵌套在父類中好。例如：

HTTP 狀態碼

REST的另外一重要部分就是爲既定好請求的類型來響應正確的狀態碼。若是你對HTTP狀態碼陌生，如下是一個簡易總結。當你請求HTTP時，服務器會響應一個狀態碼來判斷你的請求是否成功，而後客戶端應如何繼續。如下是四種不一樣層次的狀態碼：

• 2xx = Success（成功）

• 3xx = Redirect（重定向）

• 4xx = User error（客戶端錯誤）

• 5xx = Server error（服務器端錯誤）

如下是一些最重要的狀態碼：

請求成功的狀態碼：

• 200 – OK (默認的)

• 201 – Created（已建立）

• 202 – Accepted (已接受：經常使用語刪除請求)

客戶端錯誤狀態碼：

• 400 –請求出錯（語法格式有誤或服務器沒法理解此請求）

• 401 – 未受權(須要登陸)

• 404 – 找不到 (找不到所請求的文件或腳本)

• 405 – 不容許此方法(錯誤的 HTTP方法)

• 409 – 衝突 (IE嘗試以PUT請求建立相同的資源時)

API響應格式

當你請求HTTP時，你能夠請求你想要接收的格式。例如，請求一個網頁，你想以HTML的格式請求，或者若是你想要下載一張圖片，返回格式應該是圖片的格式。然而，響應請求格式是服務器的職責。

現在，JSON 已經快速發展成爲REST API選擇的格式，它有一個輕量級的、可讀性又很高的語法，以至其很容易操做。因此，當使用咱們API的用戶按他們想要的格式發出請求和指定JSON時。

要是用戶請求一個咱們沒有實現的方法的格式時，咱們又該怎麼辦呢？你大能夠拋出一些錯誤的類型。但我建議你將JSON格式做爲你的標準響應格式，由於這是開發者想要的格式。沒理由去支持其餘的格式，除非你已經有一個可支持的API。

建立一個REST API

事實上，建立一個REST API是超出此教程範圍的，由於它是有特定語言的。但我將以Ruby（一種爲簡單快捷的面向對象編程而創的腳本語言）的方式給出一個簡易例子，它使用一個叫Sinatra的類庫（不懂得能夠自行百度）。

API受權認證

在通常的網頁應用中，認證操做是常常要接收用戶名和密碼的，而後在session中保存用戶ID。用戶的瀏覽器就會保存會話中的ID到cookie中。當用戶在網站上訪問須要認證受權的頁面時，瀏覽器就會發送cookie，應用程序就會查找seesion會話中的ID（若是它沒有失效的話），因爲用戶的ID保存在seesion中，用戶就能夠瀏覽頁面了。

用這個API，就可使用seesion會話保存用戶記錄,但這畢竟不是最好的方法。有時候，用戶想直接訪問API，或是用戶想本身受權其餘應用程序去訪問這個API。

解決方法是在認證的基礎上使用祕鑰。用戶輸入用戶名和密碼以登陸，應用程序就以一個特殊祕鑰返回給用戶以備後續之需。這個祕鑰能夠通入應用程序，以致於若是用戶想要選擇拒絕應用更進一步的接入時，能夠撤回這個祕鑰。

其實，網上已經有一個作上面這件事的很流行的標準方式，叫作OAuth（開放受權：是一個開放標準，容許用戶讓第三方應用訪問該用戶在某一網站上存儲的私密的資源（如照片，視頻，聯繫人列表），與以往的受權方式不一樣之處是OAUTH的受權不會使第三方觸及到用戶的賬號信息（如用戶名與密碼），即第三方無需使用用戶的用戶名與密碼就能夠申請得到該用戶資源的受權，所以OAUTH是安全的。），特別的，標準第二版的OAuth。網上有不少很是好的實現OAuth的資源，因此我才說那是超出此教程範圍的。若是你正在使用Ruby，這裏有一些幫你解決大多數工做的很好的類庫，好比OmniAuth 。

花了那麼多時間給大家講解這個教程，但願對大家有所幫助。