REST API 的最佳入門教程

如果你看到這裡，你以前可能聽說過api 和rest,然後你就會想:“這些都是什麼東西？”。也許你已經了解過一些這方面的知識，但卻不知道從何入手。在這個教程中，我将會诠釋rest的基礎以及如何給應用建立一個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是representational state transfer的縮寫，它是由羅伊·菲爾丁(roy fielding)t提出的，是用來描述建立http api的标準方法的，他發現這四種常用的行為（檢視（view），建立(create)，編輯(edit)和删除(delete)）都可以直接映射到http 中已實作的get,post,put和delete方法。

http 中的8中不同的方法：

大多數情況下，當你在使用你的浏覽器的點點看看的時候，其實隻用到http的get方法。get方法是在你向網際網路請求資源的時候才會用到的。當你送出一個表單時，你就會經常用到post方法來回傳資料到網站上。至于其他的幾種方法，某些浏覽器可能根本就沒有去完全實作它們。但是，如果是供我們使用的話，就沒什麼問題。問題是我們有很多要選擇去幫助描述這四大行為的http方法，我們将會用到那些已經知道如何去使用這些不同的http方法的用戶端類庫。

讓我們來看下幾個讓api表述性狀态轉移化的例子，就用我們之前說的那幾個部件來解釋：

如果我們想要檢視所有部件，url将是這個樣子：

用post方法建立一個用來送出請求資料的部件：

用get方法檢視一個簡單的部件，我們從指定的部件id中擷取：

用put方法發送新資料來更新部件：

用delete方法來删除部件：

解剖rest url：

你可能已經注意的前面的幾個例子，rest url使用着一套一緻的命名方法。當你跟api互動時，你幾乎經常操作一些對象。在我們的例子中，我們講的是部件。在rest中，我們稱之為resource。url的第一部分經常是這個資源的複數形式：

當我們參考收集的資源時（list all：列出所有 和add one：新增一個），這将會經常用到。當你用到一些特殊的資源的時候，你就會給url增加一個id，這個url在你想要“view”，“edit”和“delete”特殊資源的時候會被使用。

嵌套資源：

如果說，我們的部件有很多使用者使用，url的結構又将會是怎樣的呢？

列出所有使用者

新增一個使用者

嵌套資源在url裡是完全相容的，但是超過兩層嵌套就不是很好的方法了。其實這根本不需要，因為你完全可以以id的形式參考到那些嵌套資源，總比嵌套在父類中好。例如：

這可以替換為：

甚至可以替換成這樣：

http 狀态碼：

rest的另一重要部分就是為既定好請求的類型來響應正确的狀态碼。如果你對http狀态碼陌生，以下是一個簡易總結。當你請求http時，伺服器會響應一個狀态碼來判斷你的請求是否成功，然後用戶端應如何繼續。以下是四種不同層次的狀态碼：

以下是一些最重要的狀态碼：

請求成功的狀态碼：

用戶端錯誤狀态碼：

api響應格式：

當你請求http時，你可以請求你想要接收的格式。例如，請求一個網頁，你想以html的格式請求，或者如果你想要下載下傳一張圖檔，傳回格式應該是圖檔的格式。然而，響應請求格式是伺服器的職責。

如今，json 已經快速發展成為rest api選擇的格式，它有一個輕量級的、可讀性又很高的文法，以緻其很容易操作。是以，當使用我們api的使用者按他們想要的格式送出請求和指定json時。

我們的api将會以json的格式傳回一批部件：

要是使用者請求一個我們沒有實作的方法的格式時，我們又該怎麼辦呢？你大可以抛出一些錯誤的類型。但我建議你将json格式作為你的标準響應格式，因為這是開發者想要的格式。沒理由去支援其他的格式，除非你已經有一個可支援的api。

建立一個rest api：

事實上，建立一個rest api是超出此教程範圍的，因為它是有特定語言的。但我将以ruby（一種為簡單快捷的面向對象程式設計而創的腳本語言）的方式給出一個簡易例子，它使用一個叫sinatra的類庫（不懂得可以自行百度）。

api授權認證:

在一般的網頁應用中，認證操作是經常要接收使用者名和密碼的，然後在session中儲存使用者id。使用者的浏覽器就會儲存會話中的id到cookie中。當使用者在網站上通路需要認證授權的頁面時，浏覽器就會發送cookie，應用程式就會查找seesion會話中的id（如果它沒有失效的話），由于使用者的id儲存在seesion中，使用者就可以浏覽頁面了。

用這個api，就可以使用seesion會話儲存使用者記錄,但這畢竟不是最好的方法。有時候，使用者想直接通路api，或是使用者想自己授權其他應用程式去通路這個api。

解決方法是在認證的基礎上使用秘鑰。使用者輸入使用者名和密碼以登入，應用程式就以一個特殊秘鑰傳回給使用者以備後續之需。這個秘鑰可以通入應用程式，以至于如果使用者想要選擇拒絕應用更進一步的接入時，可以撤回這個秘鑰。

花了那麼多時間給你們講解這個教程，希望對你們有所幫助。