restful規範

一、restful的引入

對資料進行增、删、改、查，在之前進行操作時可能可能是這樣寫的：

##路由比對

urlpatterns = [
    path('userlist/', views.user),
    path('useradd/', views.user),
    path('useredit/', views.user),
    path('userdelete/', views.user),
   
]      

對應的view函數中就需要對請求方法進行判斷：

def user(request):
    #處理GET請求
    if request.method == 'GET':
        return HttpResponse('GET')

    # 處理POST請求
    if request.method == 'POST':
        return HttpResponse('POST')
    
    ...      

這樣最大的問題就是随着業務的增多接口（url）會越來越多，其次是使用FBV的形式，需要對請求方法進行判斷，也是有些麻煩的，為了解決這一類的問題，就引出了restful規範。

二、restful規範

1、API與使用者的通信協定，總是使用HTTPs協定。

2、域名

#應該盡量将API部署在專用域名之下
https://api.example.com #存在跨域問題      

3、版本（Versioning）

#應該将API的版本号放入URL。
https://api.example.com/v1/      

4、路徑（Endpoint）

#視網絡上任何東西都是資源，建議url
（1）均使用名詞表示；
（2）使用複數形式；
（3）首選小寫字母；
（4）結尾不應該包含斜杠“/”；
（5）應該使用連字元”-“來提高URL的可讀性，而不是使用下劃線”_”；
　https://api.example.com/v1/users      

5、請求方法（method）

GET（SELECT）：#從伺服器取出資源（一項或多項）。
POST（CREATE）：#在伺服器建立一個資源。
PUT（UPDATE）：#在伺服器更新資源（用戶端提供改變後的完整資源）。
PATCH（UPDATE）：#在伺服器更新資源（用戶端提供改變的屬性）。
DELETE（DELETE）：#從伺服器删除資源。      

另外兩個不常用的method：

HEAD：#擷取資源的中繼資料。
OPTIONS：#擷取資訊，關于資源的哪些屬性是用戶端可以改變的。      

執行個體：

GET /depts：#列出所有部門
POST /depts：#建立一個部門
GET /depts/ID：#擷取某個指定部門的資訊
PUT /depts/ID：#更新某個指定部門的資訊（提供該動物園的全部資訊）
PATCH /depts/ID：#更新某個指定部門的資訊（提供該動物園的部分資訊）
DELETE /depts/ID：#删除某個部門
GET /depts/ID/persons：#列出某個指定部門的所有人員
DELETE /depts/ID/persons/ID：#删除某個指定部門的指定人員      

6、過濾資訊（Filtering）

#記錄數量很多，伺服器不可能都将它們傳回給使用者。API應該提供參數，過濾傳回結果
?limit=10：#指定傳回記錄的數量
?offset=10：#指定傳回記錄的開始位置。
?page=2&per_page=100：#指定第幾頁，以及每頁的記錄數。
?sortby=name&order=asc：#指定傳回結果按照哪個屬性排序，以及排序順序。
?animal_type_id=1：#指定篩選條件      

7、狀态碼（Status Codes）

200 OK - [GET]：伺服器成功傳回使用者請求的資料，該操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：使用者建立或修改資料成功。
202 Accepted - [*]：表示一個請求已經進入背景排隊（異步任務）
204 NO CONTENT - [DELETE]：使用者删除資料成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：使用者發出的請求有錯誤，伺服器沒有進行建立或修改資料的操作，該操作是幂等的。
401 Unauthorized - [*]：表示使用者沒有權限（令牌、使用者名、密碼錯誤）。
403 Forbidden - [*] 表示使用者得到授權（與401錯誤相對），但是通路是被禁止的。
404 NOT FOUND - [*]：使用者發出的請求針對的是不存在的記錄，伺服器沒有進行操作，該操作是幂等的。
406 Not Acceptable - [GET]：使用者請求的格式不可得（比如使用者請求JSON格式，但是隻有XML格式）。
410 Gone -[GET]：使用者請求的資源被永久删除，且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]：伺服器發生錯誤，使用者将無法判斷發出的請求是否成功。      

更多參見：https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

8、錯誤處理（Error handling）

如果狀态碼是4xx，就應該向使用者傳回出錯資訊。一般來說，傳回的資訊中将error作為鍵名，出錯資訊作為鍵值即可。

{
    error: "Invalid API key"
}      

9、傳回結果

針對不同操作，伺服器向使用者傳回的結果應該符合以下規範。

GET /collection：#傳回資源對象的清單（數組）
GET /collection/resource：#傳回單個資源對象
POST /collection：#傳回新生成的資源對象
PUT /collection/resource：#傳回完整的資源對象
PATCH /collection/resource：#傳回完整的資源對象
DELETE /collection/resource：#傳回一個空文檔      

10、Hypermedia API

#RESTful API最好做到Hypermedia，即傳回結果中提供連結，連向其他API方法，使得使用者不查文檔，也知道下一步應該做什麼。

#比如，當使用者向api.example.com的根目錄送出請求，會得到這樣一個文檔。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}      

參考：http://www.ruanyifeng.com/blog/2014/05/restful_api.html

作者：iveBoy

出處：http://www.cnblogs.com/shenjianping/

本文版權歸作者和部落格園共有，歡迎轉載，但未經作者同意必須在文章頁面給出原文連接配接，否則保留追究法律責任的權利。