PHPer的項目RESTful API設計規範是怎樣的？

RESTful 是目前最流行的 API 設計規範，用於 Web 數據接口的設計。

什麼是RESTful

RESTful是一種軟件設計風格, 主要用於客戶端與服務端交互的軟件. 通常來講RESTful API基於HTTP協議, 經過某個惟一標識符(URI)請求對應的服務器資源(Resource).一般咱們把RESTful API編程也叫作」接口編程」.

RESTful API基於HTTP協議, 實現了通用的先後端交互, 前端經過某個URI告訴後端執行對應的操做, 並返回須要的資源, 能夠很好的實現先後端分離.

 

什麼場景下使用RESTful API

在當今的互聯網應用的前端展現媒介很豐富。有手機、有平板電腦還有PC以及其餘的展現媒介。那麼這些前端接收到的用戶請求統一由一個後臺來處理並返回給不一樣的前端確定是最科學和最經濟的方式，RESTful API就是一套協議來規範多種形式的前端和同一個後臺的交互方式。

RESTful API由後臺也就是SERVER來提供前端來調用。前端調用API向後臺發起HTTP請求，後臺響應請求將處理結果反饋給前端。也就是說RESTful 是典型的基於HTTP的協議。那麼RESTful API有哪些設計原則和規範呢？

1，資源。首先是弄清楚資源的概念。資源就是網絡上的一個實體，一段文本，一張圖片或者一首歌曲。資源老是要經過一種載體來反應它的內容。文本能夠用TXT，也能夠用HTML或者XML、圖片能夠用JPG格式或者PNG格式，JSON是如今最經常使用的資源表現形式。

2，統一接口。RESTful風格的數據元操CRUD（create,read,update,delete）分別對應HTTP方法：GET用來獲取資源，POST用來新建資源（也能夠用於更新資源），PUT用來更新資源，DELETE用來刪除資源，這樣就統一了數據操做的接口。

3，URI。能夠用一個URI（統一資源定位符）指向資源，即每一個URI都對應一個特定的資源。要獲取這個資源訪問它的URI就能夠，所以URI就成了每個資源的地址或識別符。通常的，每一個資源至少有一個URI與之對應，最典型的URI就是URL。

4，無狀態。所謂無狀態即全部的資源均可以URI定位，並且這個定位與其餘資源無關，也不會由於其餘資源的變化而變化。有狀態和無狀態的區別，舉個例子說明一下：

例如要查詢員工工資的步驟爲第一步：登陸系統。第二步：進入查詢工資的頁面。第三步：搜索該員工。第四步：點擊姓名查看工資。這樣的操做流程就是有狀態的，查詢工資的每個步驟都依賴於前一個步驟，只要前置操做不成功，後續操做就沒法執行。

若是輸入一個URL就能夠獲得指定員工的工資，則這種狀況就是無狀態的，由於獲取工資不依賴於其餘資源或狀態，且這種狀況下，員工工資是一個資源，由一個URL與之對應能夠經過HTTP中的GET方法獲得資源，這就是典型的RESTful風格。

RESTful 的設計細節

一 URL設計

動詞+賓語

RESTful的核心思想就是，客戶端發出的數據+操做指令都是「動詞+賓語」的結構，好比GET /articles這個命令，GET是動詞，/articles是賓語，動詞一般就有5種HTTP請求方法，對應CRUD操做，根據 HTTP 規範，動詞一概大寫。

 

 

動詞的覆蓋

有些客戶端只能使用GET和POST這兩種方法。服務器必須接受POST模擬其餘三個方法（PUT、PATCH、DELETE）。這時，客戶端發出的 HTTP 請求，要加上X-HTTP-Method-Override屬性，告訴服務器應該使用哪個動詞，覆蓋POST方法。

 

 

上面代碼中，X-HTTP-Method-Override指定本次請求的方法是PUT，而不是POST。

賓語必須是名詞

賓語就是 API 的 URL，是 HTTP 動詞做用的對象。它應該是名詞，不能是動詞。好比，/articles這個 URL 就是正確的，而下面的 URL 不是名詞，因此都是錯誤的。

 

 

複數 URL

既然 URL 是名詞，那麼應該使用複數，仍是單數？這沒有統一的規定，可是常見的操做是讀取一個集合，好比GET /articles（讀取全部文章），這裏明顯應該是複數。

爲了統一塊兒見，建議都使用複數 URL，好比GET /articles/2要好於GET /article/2。

避免多級 URL

常見的狀況是，資源須要多級分類，所以很容易寫出多級的 URL，好比獲取某個做者的某一類文章。

 

 

這種 URL 不利於擴展，語義也不明確，每每要想一會，才能明白含義。

更好的作法是，除了第一級，其餘級別都用查詢字符串表達。

 

 下面是另外一個例子，查詢已發佈的文章。你可能會設計成下面的 URL。

 

 查詢字符串的寫法明顯更好

 

 

2、狀態碼

狀態碼必須精確

客戶端的每一次請求，服務器都必須給出迴應。迴應包括 HTTP 狀態碼和數據兩部分。

HTTP 狀態碼就是一個三位數，分紅五個類別。

 

 

這五大類總共包含100多種狀態碼，覆蓋了絕大部分可能遇到的狀況。每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需查看狀態碼，就能夠判斷出發生了什麼狀況，因此服務器應該返回儘量精確的狀態碼。

API 不須要1xx狀態碼，下面介紹其餘四類狀態碼的精確含義。

2XX狀態碼

200狀態碼錶示操做成功，可是不一樣的方法能夠返回更精確的狀態碼。

 

 

上面代碼中，POST返回201狀態碼，表示生成了新的資源；DELETE返回204狀態碼，表示資源已經不存在。

此外，202 Accepted狀態碼錶示服務器已經收到請求，但還未進行處理，會在將來再處理，一般用於異步操做。下面是一個例子。

 

 

3xx 狀態碼

API 用不到301狀態碼（永久重定向）和302狀態碼（暫時重定向，307也是這個含義），由於它們能夠由應用級別返回，瀏覽器會直接跳轉，API 級別能夠不考慮這兩種狀況。

API 用到的3xx狀態碼，主要是303 See Other，表示參考另外一個 URL。它與302和307的含義同樣，也是"暫時重定向"，區別在於302和307用於GET請求，而303用於POST、PUT和DELETE請求。收到303之後，瀏覽器不會自動跳轉，而會讓用戶本身決定下一步怎麼辦。

下面是一個例子。

 

 

4xx 狀態碼

4xx狀態碼錶示客戶端錯誤，主要有下面幾種。

• 400 Bad Request：服務器不理解客戶端的請求，未作任何處理。

• 401 Unauthorized：用戶未提供身份驗證憑據，或者沒有經過身份驗證。

• 403 Forbidden：用戶經過了身份驗證，可是不具備訪問資源所需的權限。

• 404 Not Found：所請求的資源不存在，或不可用。

• 405 Method Not Allowed：用戶已經經過身份驗證，可是所用的 HTTP 方法不在他的權限以內。

• 410 Gone：所請求的資源已從這個地址轉移，再也不可用。

• 415 Unsupported Media Type：客戶端要求的返回格式不支持。好比，API 只能返回 JSON 格式，可是客戶端要求返回 XML 格式。

• 422 Unprocessable Entity ：客戶端上傳的附件沒法處理，致使請求失敗。

• 429 Too Many Requests：客戶端的請求次數超過限額。

5xx 狀態碼

5xx狀態碼錶示服務端錯誤。通常來講，API 不會向用戶透露服務器的詳細信息，因此只要兩個狀態碼就夠了。

• 500 Internal Server Error：客戶端請求有效，服務器處理時發生了意外。

• 503 Service Unavailable：服務器沒法處理請求，通常用於網站維護狀態。

 

3、服務器迴應

不要返回純本文

API 返回的數據格式，不該該是純文本，而應該是一個 JSON 對象，由於這樣才能返回標準的結構化數據。因此，服務器迴應的 HTTP 頭的Content-Type屬性要設爲application/json。

客戶端請求時，也要明確告訴服務器，能夠接受 JSON 格式，即請求的 HTTP 頭的ACCEPT屬性也要設成application/json。下面是一個例子。

 

 

發生錯誤時，不要返回 200 狀態碼

有一種不恰當的作法是，即便發生錯誤，也返回200狀態碼，把錯誤信息放在數據體裏面，就像下面這樣。

 

 

上面代碼中，解析數據體之後，才能得知操做失敗。

這張作法實際上取消了狀態碼，這是徹底不可取的。正確的作法是，狀態碼反映發生的錯誤，具體的錯誤信息放在數據體裏面返回。下面是一個例子。

 

 

提供連接

API 的使用者未必知道，URL 是怎麼設計的。一個解決方法就是，在迴應中，給出相關連接，便於下一步操做。這樣的話，用戶只要記住一個 URL，就能夠發現其餘的 URL。這種方法叫作 HATEOAS。

舉例來講，GitHub 的 API 都在 api.github.com 這個域名。訪問它，就能夠獲得其餘 URL。

 

 

上面的迴應中，挑一個 URL 訪問，又能夠獲得別的 URL。對於用戶來講，不須要記住 URL 設計，只要從 api.github.com 一步步查找就能夠了。

HATEOAS 的格式沒有統一規定，上面例子中，GitHub 將它們與其餘屬性放在一塊兒。更好的作法應該是，將相關連接與其餘屬性分開。

 

 

以上是文章所有內容，有須要學習交流的友人請加入交流羣的我們一塊兒，有問題一塊兒交流，一塊兒進步！前提是你是學技術的。感謝閱讀！

點此加入該羣