RESTful API規范

本文轉載自查看原文 2018-09-11 04:49 1628 Django

RESTful 規范指南:

1. HTTP 協議

API 與用戶的通信協議, 總是使用 HTTPS 協議

2. 域名:

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  # 子域名方式:(解決跨域的問題) 
                  
                  
                   www.baidu.com 
                  
                  
                   api.baidu.com 
                  
                  
                  # 存在跨域的風險 
                  
                  
                       
                  
                  
                       
                  
                  
                  # ========================================= 
                  
                  
                  # URL 方式: 
                  
                  
                   www.baidu.com 
                  
                  
                   www.baidu.com/api/

3. 版本:

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  URL  如: https://api.baidu.com/v1/    
                  
                  
                  # 一般情況下都放在 url 上 
                  
                  
                  請求頭:                           跨域時, 引發發送多次請求

4. 路徑

視網絡上的一切都為資源, 均使用名詞表示(可使用復數)

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  https://api.baidu.com/v1/zoos 
                  
                  
                  https://api.baidu.com/v1/animals 
                  
                  
                  https://api.baidu.com/v1/employees

5. method

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  GET:     從服務器取出資源(一項或多項) 
                  
                  
                  POST:    在服務器新建一個資源 
                  
                  
                  PUT:     在服務器更新資源( 客戶端提供改變后的完整資源 ) 
                  
                  
                  PATCH:   在服務器更新資源( 客戶端提供改變的屬性 ) 
                  
                  
                  DELETE:  在服務器刪除資源

6. 過濾:

通過在 URL 上傳參的形式傳遞搜索條件

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  https://api.baidu.com/v1/zoos?limit=10      : 指定返回記錄的數量 
                  
                 https://api.baidu.com/v1/zoos?offset=10     : 指定返回記錄的開始位置 
                 https://api.baidu.com/v1/zoos?page=2&per_page=100  : 指定第幾頁, 以及每頁的記錄數 
                 https://api.baidu.com/v1/zoos?sortby=name&order=asc    : 指定返回結果按照那個屬性排序, 以及排序順序 
                 https://api.baidu.com/v1/zoos?animal_type_id = 1        : 指定篩選條件

7. 狀態碼:

常用狀態碼:

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  200 – OK – 一切正常  
                  
                 201 – OK – 新資源已經被創建  
                 204 – OK – 資源刪除成功 
                  
                 304 – 沒有變化，客戶端可以使用緩存數據 
                  
                 400 – Bad Request – 調用不合法，確切的錯誤應該在error payload中描述，例如：“JSON 不合法 ”  
                 401 – 未認證，調用需要用戶通過認證  
                 403 – 不允許的，服務端正常解析和請求，但是調用被回絕或者不被允許  
                 404 – 未找到，指定的資源不存在  
                 422 – 不可指定的請求體 – 只有服務器不能處理實體時使用，比如圖像不能被格式化，或者重要字段丟失。 
                  
                 500 – Internal Server Error – 標准服務端錯誤，API開發人員應該盡量避開這種錯誤

狀態碼和 code 結合使用
全部狀態碼:

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  建議不要在回復中使用裸狀態代碼。REST框架包含一組命名常量，您可以使用這些常量使代碼更加明顯和可讀。 
                  
                  
                 from rest_framework import status 
                 from rest_framework.response import Response 
                  
                 def empty_view(self): 
                     content = {'please move along': 'nothing to see here'} 
                     return Response(content, status=status.HTTP_404_NOT_FOUND) 
                  
                  
                 # ========================================================= 
                 status下面列出了模塊中包含的完整HTTP狀態代碼集。 
                  
                 該模塊還包括一組輔助函數，用於測試狀態代碼是否在給定范圍內。 
                  
                 from rest_framework import status 
                 from rest_framework.test import APITestCase 
                  
                 class ExampleTestCase(APITestCase): 
                     def test_url_root(self): 
                         url = reverse('index') 
                         response = self.client.get(url) 
                         self.assertTrue(status.is_success(response.status_code)) 
                 有關正確使用HTTP狀態代碼的詳細信息，請參閱RFC 2616 和RFC 6585。 
                 # ========================================================= 
                 信息 - 1xx 
                 此類狀態代碼表示臨時響應。默認情況下，REST框架中沒有使用1xx狀態代碼。 
                  
                 HTTP_100_CONTINUE 
                 HTTP_101_SWITCHING_PROTOCOLS 
                  
                 # ========================================================= 
                 成功 - 2xx 
                 此類狀態代碼表示已成功接收，理解和接受客戶端的請求。 
                  
                 HTTP_200_OK 
                 HTTP_201_CREATED 
                 HTTP_202_ACCEPTED 
                 HTTP_203_NON_AUTHORITATIVE_INFORMATION 
                 HTTP_204_NO_CONTENT 
                 HTTP_205_RESET_CONTENT 
                 HTTP_206_PARTIAL_CONTENT 
                 HTTP_207_MULTI_STATUS 
                  
                 # ========================================================= 
                 重定向 - 3xx 
                 此類狀態代碼指示用戶代理需要采取進一步操作才能完成請求。 
                  
                 HTTP_300_MULTIPLE_CHOICES 
                 HTTP_301_MOVED_PERMANENTLY 
                 HTTP_302_FOUND 
                 HTTP_303_SEE_OTHER 
                 HTTP_304_NOT_MODIFIED 
                 HTTP_305_USE_PROXY 
                 HTTP_306_RESERVED 
                 HTTP_307_TEMPORARY_REDIRECT 
                  
                 # ========================================================= 
                 客戶端錯誤 - 4xx 
                 4xx類狀態代碼適用於客戶端似乎有錯誤的情況。除了在響應HEAD請求時，服務器應該包括一個實體，其中包含錯誤情況的解釋，以及它是暫時的還是永久的。 
                  
                 HTTP_400_BAD_REQUEST 
                 HTTP_401_UNAUTHORIZED 
                 HTTP_402_PAYMENT_REQUIRED 
                 HTTP_403_FORBIDDEN 
                 HTTP_404_NOT_FOUND 
                 HTTP_405_METHOD_NOT_ALLOWED 
                 HTTP_406_NOT_ACCEPTABLE 
                 HTTP_407_PROXY_AUTHENTICATION_REQUIRED 
                 HTTP_408_REQUEST_TIMEOUT 
                 HTTP_409_CONFLICT 
                 HTTP_410_GONE 
                 HTTP_411_LENGTH_REQUIRED 
                 HTTP_412_PRECONDITION_FAILED 
                 HTTP_413_REQUEST_ENTITY_TOO_LARGE 
                 HTTP_414_REQUEST_URI_TOO_LONG 
                 HTTP_415_UNSUPPORTED_MEDIA_TYPE 
                 HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE 
                 HTTP_417_EXPECTATION_FAILED 
                 HTTP_422_UNPROCESSABLE_ENTITY 
                 HTTP_423_LOCKED 
                 HTTP_424_FAILED_DEPENDENCY 
                 HTTP_428_PRECONDITION_REQUIRED 
                 HTTP_429_TOO_MANY_REQUESTS 
                 HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE 
                 HTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS 
                  
                 # ========================================================= 
                 服務器錯誤 - 5xx 
                 以數字“5”開頭的響應狀態代碼表示服務器知道它已經錯誤或無法執行請求的情況。除了在響應HEAD請求時，服務器應該包括一個實體，其中包含錯誤情況的解釋，以及它是暫時的還是永久的。 
                  
                 HTTP_500_INTERNAL_SERVER_ERROR 
                 HTTP_501_NOT_IMPLEMENTED 
                 HTTP_502_BAD_GATEWAY 
                 HTTP_503_SERVICE_UNAVAILABLE 
                 HTTP_504_GATEWAY_TIMEOUT 
                 HTTP_505_HTTP_VERSION_NOT_SUPPORTED 
                 HTTP_507_INSUFFICIENT_STORAGE 
                 HTTP_511_NETWORK_AUTHENTICATION_REQUIRED 
                  
                 # ========================================================= 
                 助手功能 
                 以下輔助函數可用於標識響應代碼的類別。 
                  
                 is_informational()  # 1xx 
                 is_success()        # 2xx 
                 is_redirect()       # 3xx 
                 is_client_error()   # 4xx 
                 is_server_error()   # 5xx

8. 錯誤處理

狀態碼是 4xx 時, 應返回錯誤信息, error 當作 key

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  { 
                  
                  
                      error: 'Invalid API key' 
                  
                  
                  }

9. 返回結果

針對不同操作, 服務器向用戶返回的結果應該符合以下規范:

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                  GET /collection: 返回資源對象的列表 (數組) 
                  
                 GET /collection/resource: 返回單個資源對象 
                  
                   
                   
                  POST /collection: 返回新生成的資源對象 
                  
                 PUT /collection/resource:  返回完整的資源對象 
                 PATCH /collection/resource: 返回完整的資源對象 
                 DELETE /collection/resource: 返回一個空文檔

Restful API 的設計規范–進階篇原文鏈接

本文總結了 RESTful API 設計相關的一些原則，只覆蓋了常見的場景。有些規則只是針對自己項目而言，並非其他做法都是錯誤的。

1. URI

URI 表示資源，資源一般對應服務器端領域模型中的實體類。 URI規范

不用大寫;
用中杠-而不用下杠_;
參數列表要encode;
URI中的名詞表示資源集合，使用復數形式;

資源集合與單個資源 資源集合：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      /zoos //所有動物園 
                  
                     /zoos/1/animals //id為1的動物園內的所有動物

單個資源：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      /zoos/1 //id為1的動物園 
                  
                     /zoos/1;2;3 //id為1,2,3的動物園

避免層級過深的URI /在URI中表示層級，用於按實體關聯關系進行對象導航，一般跟進id導航; 過深的導航容易導致url膨脹，不易維護，如 GET /zoos/1/areas/3/animals/4，盡量使用查詢參數代替路徑中的實體導航，如GET /animals?zoo=1&area=3;

對Composite資源的訪問 服務器端的組合實體必須在uri中通過父實體的id導航訪問。

組合實體不是first-class的實體，它的生命周期完全依賴父實體，無法獨立存在，在實現上通常是對數據庫表中某些列的抽象，不直接對應表，也無id。一個常見的例子是 User — Address，Address是對User表中zipCode/country/city三個字段的簡單抽象，無法獨立於User存在。必須通過User索引到Address：GET /user/1/addresses

2. Request

HTTP方法 通過標准HTTP方法對資源CRUD： GET: 查詢

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      GET /zoos 
                  
                     GET /zoos/1 
                     GET /zoos/1/employees

POST: 創建單個資源。POST一般向“資源集合”型URI發起； ··· javaascipt

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  POST /animals //新增動物 
                  
                 POST /zoos/1/employees //id為1的動物園的所有員工

PUT：更新單個資源（全量），客戶端提供完整的更新后的資源。與之對應的是 PATCH，PATCH 負責部分更新，客戶端提供要更新的那些字段。PUT/PATCH一般向“單個資源”型uri發起

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      PUT /animals/1 
                  
                     PUT /zoos/1

DELETE：刪除

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      DELETE /zoos/1/employees/2 
                  
                     DELETE /zoos/1/employees/2;4;5 
                     DELETE /zoos/1/animals  //刪除id為1的動物園內的所有動物

HEAD / OPTION 用的不多，就不多解釋了。

安全性與冪等性 安全性：不會改變資源狀態，可以理解為只讀的；冪等性：執行1次和執行N次，對資源狀態改變的效果是等價的。圖片描述

安全性和冪等性均不保證反復請求能拿到相同的response。以 DELETE 為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。

復雜查詢 查詢可以捎帶以下參數：圖片描述

Bookmarker 經常使用的、復雜的查詢標簽化，降低維護成本。如：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  GET /trades?status=closed&sort=created,desc

快捷方式：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      GET /trades#recently-closed 
                  
                     // 或者 
                     GET /trades/recently-closed

Format 只用以下常見的3種body format：

Content-Type: application/json

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      POST /v1/animal HTTP/1.1 
                  
                     Host: api.example.org 
                     Accept: application/json 
                     Content-Type: application/json 
                     Content-Length: 24 
                  
                     {    
                       "name": "Gir", 
                       "animalType": "12" 
                     }

Content-Type: application/x-www-form-urlencoded (瀏覽器POST表單用的格式)

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      POST /login HTTP/1.1 
                  
                     Host: example.com 
                     Content-Length: 31 
                     Accept: text/html 
                     Content-Type: application/x-www-form-urlencoded 
                      
                     username=root&password=Zion0101

Content-Type: multipart/form-data; boundary=—-RANDOM_jDMUxq4Ot5 (表單有文件上傳時的格式)

Content Negotiation 資源可以有多種表示方式，如json、xml、pdf、excel等等，客戶端可以指定自己期望的格式，通常有兩種方式：

http header Accept：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                  Accept:application/xml;q=0.6,application/atom+xml;q=1.0

q為各項格式的偏好程度

url中加文件后綴：/zoo/1.json

3. Response

不要包裝
response 的 body 直接就是數據，不要做多余的包裝。錯誤示例：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      { 
                  
                         "success":true, 
                         "data":{"id":1,"name":"xiaotuan"}, 
                     }

各HTTP方法成功處理后的數據格式：
json格式的約定：時間用長整形(毫秒數)，客戶端自己按需解析（moment.js）不傳null字段

分頁response

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      { 
                  
                         "paging":{"limit":10,"offset":0,"total":729}, 
                         "data":[{},{},{}...] 
                     }

4. 錯誤處理

不要發生了錯誤但給2xx響應，客戶端可能會緩存成功的http請求；
正確設置http狀態碼，不要自定義；
Response body 提供 1) 錯誤的代碼（日志/問題追查）；2) 錯誤的描述文本（展示給用戶）。

對第三點的實現稍微多說一點： Java 服務器端一般用異常表示 RESTful API 的錯誤。API 可能拋出兩類異常：業務異常和非業務異常。業務異常由自己的業務代碼拋出，表示一個用例的前置條件不滿足、業務規則沖突等，比如參數校驗不通過、權限校驗失敗。非業務類異常表示不在預期內的問題，通常由類庫、框架拋出，或由於自己的代碼邏輯錯誤導致，比如數據庫連接失敗、空指針異常、除0錯誤等等。業務類異常必須提供2種信息：

如果拋出該類異常，HTTP 響應狀態碼應該設成什么；
異常的文本描述；

在Controller層使用統一的異常攔截器：

設置 HTTP 響應狀態碼：對業務類異常，用它指定的 HTTP code；對非業務類異常，統一500；
Response Body 的錯誤碼：異常類名
Response Body 的錯誤描述：對業務類異常，用它指定的錯誤文本；對非業務類異常，線上可以統一文案如“服務器端錯誤，請稍后再試”，開發或測試環境中用異常的 stacktrace，服務器端提供該行為的開關。

常用的http狀態碼及使用場景：

5. 服務型資源

除了資源簡單的CRUD，服務器端經常還會提供其他服務，這些服務無法直接用上面提到的URI映射。如：

按關鍵字搜索；
計算地球上兩點間的距離；
批量向用戶推送消息;

可以把這些服務看成資源，計算的結果是資源的presentation，按服務屬性選擇合適的HTTP方法。例如：

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      GET /search?q=filter?category=file  搜索 
                  
                     GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448 
                     POST /batch-publish-msg 
                     [{"from":0,"to":1,"text":"abc"},{},{}...]

6. 異步任務

對耗時的異步任務，服務器端接受客戶端傳遞的參數后，應返回創建成功的任務資源，其中包含了任務的執行狀態。客戶端可以輪訓該任務獲得最新的執行進度。

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      // 提交任務： 
                  
                     POST /batch-publish-msg 
                     [{"from":0,"to":1,"text":"abc"},{},{}...] 
                      
                     // 返回： 
                     {"taskId":3,"createBy":"Anonymous","status":"running"} 
                      
                     GET /task/3 
                     {"taskId":3,"createBy":"Anonymous","status":"success"}

如果任務的執行狀態包括較多信息，可以把“執行狀態”抽象成組合資源，客戶端查詢該狀態資源了解任務的執行情況。

  
  
  
          
   
   
   
            
             
           
   
   
   
            
             
              
               
                
                 
                  
                 
                 
                 
                 
                  
                   
                   
                      提交任務： 
                  
                     POST /batch-publish-msg 
                     [{"from":0,"to":1,"text":"abc"},{},{}...] 
                      
                     返回： 
                     {"taskId":3,"createBy":"Anonymous"} 
                      
                     GET /task/3/status 
                     {"progress":"50%","total":18,"success":8,"fail":1}

7. API演進

版本常見的三種方式：

在uri中放版本信息：GET /v1/users/1
Accept Header：Accept: application/json+v1
自定義 Header：X-Api-Version: 1

用第一種，雖然沒有那么優雅，但最明顯最方便。

URI失效 隨着系統發展，總有一些API失效或者遷移，對失效的API，返回404 not found 或 410 gone；對遷移的API，返回 301 重定向。

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 RESTful api接口規范 Restful API接口規范 Restful API接口規范 Restful API接口規范 restful API 規范（轉） Restful API接口規范 RESTful API規范 Restful API 接口與規范 RESTful API設計原則與規范 RESTful api 設計規范