簡(jiǎn)潔 RESTful API 設(shè)計(jì)規(guī)范！整個(gè)人都清爽了！

動(dòng)詞+賓語(yǔ)

# GET：讀?。≧ead）# POST：新建（Create）# PUT：更新（Update）# PATCH：更新（Update），通常是部分更新# DELETE：刪除（Delete）

動(dòng)詞的覆蓋

POST /api/Person/4 HTTP/1.1  X-HTTP-Method-Override: PUT

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

賓語(yǔ)必須是名詞

# /getAllCars# /createNewCar# /deleteAllRedCars

復(fù)數(shù) URL

避免多級(jí) URL

常見(jiàn)的情況是，資源需要多級(jí)分類，因此很容易寫(xiě)出多級(jí)的 URL，比如獲取某個(gè)作者的某一類文章。

# GET /authors/12/categories/2

這種 URL 不利于擴(kuò)展，語(yǔ)義也不明確，往往要想一會(huì)，才能明白含義。

更好的做法是，除了第一級(jí)，其他級(jí)別都用查詢字符串表達(dá)。

# GET /authors/12?categories=2

下面是另一個(gè)例子，查詢已發(fā)布的文章。你可能會(huì)設(shè)計(jì)成下面的 URL。

# GET /articles/published

查詢字符串的寫(xiě)法明顯更好

# GET /articles?published=true

狀態(tài)碼必須精確

客戶端的每一次請(qǐng)求，服務(wù)器都必須給出回應(yīng)?；貞?yīng)包括 HTTP 狀態(tài)碼和數(shù)據(jù)兩部分。

HTTP 狀態(tài)碼就是一個(gè)三位數(shù)，分成五個(gè)類別。

# 1xx：相關(guān)信息# 2xx：操作成功# 3xx：重定向# 4xx：客戶端錯(cuò)誤# 5xx：服務(wù)器錯(cuò)誤

這五大類總共包含100多種狀態(tài)碼，覆蓋了絕大部分可能遇到的情況。每一種狀態(tài)碼都有標(biāo)準(zhǔn)的（或者約定的）解釋，客戶端只需查看狀態(tài)碼，就可以判斷出發(fā)生了什么情況，所以服務(wù)器應(yīng)該返回盡可能精確的狀態(tài)碼。

API 不需要1xx狀態(tài)碼，下面介紹其他四類狀態(tài)碼的精確含義。

2XX狀態(tài)碼

200狀態(tài)碼表示操作成功，但是不同的方法可以返回更精確的狀態(tài)碼。

# GET: 200 OK# POST: 201 Created# PUT: 200 OK# PATCH: 200 OK# DELETE: 204 No Content

HTTP/1.1 202 Accepted
{  "task": {    "href": "/api/company/job-management/jobs/2130040",    "id": "2130040"  }}

3xx 狀態(tài)碼

API 用不到301狀態(tài)碼（永久重定向）和302狀態(tài)碼（暫時(shí)重定向，307也是這個(gè)含義），因?yàn)樗鼈兛梢杂蓱?yīng)用級(jí)別返回，瀏覽器會(huì)直接跳轉(zhuǎn)，API 級(jí)別可以不考慮這兩種情況。

API 用到的3xx狀態(tài)碼，主要是303 See Other，表示參考另一個(gè) URL。它與302和307的含義一樣，也是"暫時(shí)重定向"，區(qū)別在于302和307用于GET請(qǐng)求，而303用于POST、PUT和DELETE請(qǐng)求。收到303以后，瀏覽器不會(huì)自動(dòng)跳轉(zhuǎn)，而會(huì)讓用戶自己決定下一步怎么辦。下面是一個(gè)例子。

HTTP/1.1 303 See OtherLocation: /api/orders/12345

4xx 狀態(tài)碼

4xx狀態(tài)碼表示客戶端錯(cuò)誤，主要有下面幾種。

400 Bad Request：服務(wù)器不理解客戶端的請(qǐng)求，未做任何處理。

401 Unauthorized：用戶未提供身份驗(yàn)證憑據(jù)，或者沒(méi)有通過(guò)身份驗(yàn)證。

403 Forbidden：用戶通過(guò)了身份驗(yàn)證，但是不具有訪問(wèn)資源所需的權(quán)限。

404 Not Found：所請(qǐng)求的資源不存在，或不可用。

405 Method Not Allowed：用戶已經(jīng)通過(guò)身份驗(yàn)證，但是所用的 HTTP 方法不在他的權(quán)限之內(nèi)。

410 Gone：所請(qǐng)求的資源已從這個(gè)地址轉(zhuǎn)移，不再可用。

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

422 Unprocessable Entity ：客戶端上傳的附件無(wú)法處理，導(dǎo)致請(qǐng)求失敗。

429 Too Many Requests：客戶端的請(qǐng)求次數(shù)超過(guò)限額。

5xx 狀態(tài)碼

5xx狀態(tài)碼表示服務(wù)端錯(cuò)誤。一般來(lái)說(shuō)，API 不會(huì)向用戶透露服務(wù)器的詳細(xì)信息，所以只要兩個(gè)狀態(tài)碼就夠了。

500 Internal Server Error：客戶端請(qǐng)求有效，服務(wù)器處理時(shí)發(fā)生了意外。

503 Service Unavailable：服務(wù)器無(wú)法處理請(qǐng)求，一般用于網(wǎng)站維護(hù)狀態(tài)。

不要返回純本文

API 返回的數(shù)據(jù)格式，不應(yīng)該是純文本，而應(yīng)該是一個(gè) JSON 對(duì)象，因?yàn)檫@樣才能返回標(biāo)準(zhǔn)的結(jié)構(gòu)化數(shù)據(jù)。所以，服務(wù)器回應(yīng)的 HTTP 頭的Content-Type屬性要設(shè)為application/json。

客戶端請(qǐng)求時(shí)，也要明確告訴服務(wù)器，可以接受 JSON 格式，即請(qǐng)求的 HTTP 頭的ACCEPT屬性也要設(shè)成application/json。下面是一個(gè)例子。

GET /orders/2 HTTP/1.1 Accept: application/json

發(fā)生錯(cuò)誤時(shí)，不要返回 200 狀態(tài)碼

有一種不恰當(dāng)?shù)淖龇ㄊ?，即使發(fā)生錯(cuò)誤，也返回200狀態(tài)碼，把錯(cuò)誤信息放在數(shù)據(jù)體里面，就像下面這樣。

HTTP/1.1 200 OKContent-Type: application/json
{  "status": "failure",  "data": {    "error": "Expected at least two items in list."  }}

上面代碼中，解析數(shù)據(jù)體以后，才能得知操作失敗。

這張做法實(shí)際上取消了狀態(tài)碼，這是完全不可取的。正確的做法是，狀態(tài)碼反映發(fā)生的錯(cuò)誤，具體的錯(cuò)誤信息放在數(shù)據(jù)體里面返回。下面是一個(gè)例子。

HTTP/1.1 400 Bad RequestContent-Type: application/json
{  "error": "Invalid payoad.",  "detail": {     "surname": "This field is required."  }}

提供鏈接

API 的使用者未必知道，URL 是怎么設(shè)計(jì)的。一個(gè)解決方法就是，在回應(yīng)中，給出相關(guān)鏈接，便于下一步操作。這樣的話，用戶只要記住一個(gè) URL，就可以發(fā)現(xiàn)其他的 URL。這種方法叫做 HATEOAS。

舉例來(lái)說(shuō)，GitHub 的 API 都在 api.github.com 這個(gè)域名。訪問(wèn)它，就可以得到其他 URL。

{  ...  "feeds_url": "https://api.github.com/feeds",  "followers_url": "https://api.github.com/user/followers",  "following_url": "https://api.github.com/user/following{/target}",  "gists_url": "https://api.github.com/gists{/gist_id}",  "hub_url": "https://api.github.com/hub",  ...}

上面的回應(yīng)中，挑一個(gè) URL 訪問(wèn)，又可以得到別的 URL。對(duì)于用戶來(lái)說(shuō)，不需要記住 URL 設(shè)計(jì)，只要從 api.github.com 一步步查找就可以了。

HATEOAS 的格式?jīng)]有統(tǒng)一規(guī)定，上面例子中，GitHub 將它們與其他屬性放在一起。更好的做法應(yīng)該是，將相關(guān)鏈接與其他屬性分開(kāi)。

HTTP/1.1 200 OKContent-Type: application/json
{  "status": "In progress",   "links": {[    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,    { "rel":"edit", "method": "put", "href":"/api/status/12345" }  ]}
}

   

    

     

      

       

        

         

          

           

            

           
          
          

           

            
參考鏈接
           
          
         
        
       
      
     
    
   

• RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca

• API design, by MicroSoft Azure 

作者：馬一特

鏈接:cnblogs.com/mayite/p/9798913.html

?長(zhǎng)按上方二維碼 2 秒
回復(fù)「數(shù)據(jù)結(jié)構(gòu)」即可獲取資料

點(diǎn)贊是最大的支持