9-django——restful設計風格

RESTful Api設計風格

協議：API與用戶的通訊協議，老是使用HTTPS協議

域名：應該儘可能將API部署在專用域名之下，若是肯定API很簡單，不會有進一步的擴展，能夠考慮放在主域名之下。

版本：

• 應該將API的版本放在URL中：https://www.sunck.wang/api/v1.0
• 將版本號放在HTTP頭信息中：https://www.sunck.wang/students

路徑：表示API的具體網址，每一個網址表明一種資源，因此網址中不能有動詞，只能有名詞，而且所用的名詞每每與數據庫的表名對應。數據庫中的表示記錄同種數據的集合，因此API中的名詞也應該使用複數。

獲取全部學生：

• https://www.sunck.wang/api/v1... 錯誤寫法
• https://www.sunck.wang/api/v1... 正確寫法

使用正確的HTTP請求方法

方式	解釋
GET select	從服務器獲取資源(一項或者多項)
POST create	在服務器新建一個資源
PUT update	在服務器更新資源(客戶端提供改變後的完整資源)
PATCH update	在服務器更新資源(客戶端提供改的屬性)
DELETE delete	從服務器刪除資源
HEAD	獲取資源的元數據
OPTIONS	獲取信息，關於資源的哪些屬性是客戶端能夠改變的

例子

描述	方式
列出全部班級	GET /grades/
獲取某個指定班級編號的信息	GET /grades/id
列出某個指定編號的班級的全部學生	GET /grades/id/students/
獲取某個指定編號的學生信息	GET /students/id
建立一個學生	POST /students/
更新某個指定學生的信息(信息所有由客戶端提供)	PUT /students/id
刪除某個指定編號的學生	DELETE /students/id
刪除某個指定班級的下的全部學生	DELETE /grades/id/students/

過濾信息

若是資源數較多，服務器不能將全部數據一次所有返回給客戶端，API應該提供參數，過濾返回結果

例子

描述	方式
指定返回記錄的數量	GET /students/?limit=
指定返回記錄的開始位置	GET /students/?offset=
指定返回第幾頁數據，以及每頁的記錄數	GET /students/?page=&per_page=
指定返回結果按照哪一個屬性排序，以及排序的順序	GET /students/?sortby=&order=
指定篩選條件	GET /students/?student_age_gt=

注意：參數的設計容許存在冗餘，即容許API路徑和URL參數偶爾有重複

狀態碼

服務器向客戶端返回的狀態碼和提示信息

錯誤處理

若是錯誤碼是4xx，就應該向用戶返回錯誤信息，通常來講，返回的信息中將error做爲鍵名，出錯的信息做爲鍵值便可

{
    error:'Invalid API KEY',
}

響應結果

針對不一樣的操做，服務器向用戶返回結果應該符合規範

方式	描述
GET /students/	返回資源對象的列表
GET /students/id/	返回單個資源對象
POST /students/	返回新生成的資源對象
PUT /students/	返回完整的資源對象
PATCH /students/	返回完整的資源對象
DELETE /students/id/	返回一個空文檔

使用連接相關的資源

返回結果中提供了連接，鏈向了其餘的API方法，使得用戶不查看文檔，也知道下一步應該作什麼

示例

{
    link:"www.sunck.wang/grades/"
}
{
    "link":{
        "rel":"collection www.sunck.wang/index/",
        "href":"www.sunck.wang/grades/",
        "title":"List of Grades",
        "type":"application/json",
    }
}

鍵

rel：表示這個API與當前網址的關係

href：表示API路徑

title：表示API的標題

type：表示返回的類型

其餘：服務器返回的數據儘可能使用JSON格式，避免使用XML格式

API文檔規範要求

1、 寫明該接口的功能是什麼

2、 請求的URL是什麼

3、 請求方式是什麼（POST、GET、 DELETE、PUT、 PATCH等）

4、 參數是什麼，此處還需說明你的參數名、參數類型、是否必填、參數的簡單解釋

5、 請求成功時的響應內容（實際開發中，要與前端同事溝通使用什麼樣的數據結構），而且對其中的字段作出說明（包括含義、數據類型，數據結構<字符串，數組，字典等>）

6、 請求失敗時的響應內容，而且對其中的字段作出說明（包括含義、數據類型，數據結構<字符串，數組，字典等>）包括單獨的對錯誤碼的說明

7、 請求樣例（返回結果部分要包括成功的狀況和失敗的狀況）

8、 最好寫上文檔的編寫人和編寫時間（可不寫）

Demo：

​ 功能：獲取某人的下屬

​ URL：」people/api/v1/ subordinate」

請求參數說明：

參數名	類型	是否必填	備註
uid	int	是	用戶的id

請求成功參數說明

參數名	類型	說明
code	Int	響應狀態碼1表明成功
msg	string	響應信息
data	數組	數組內是字典類型，詳情見下表

data內的響應參數說明

參數名	類型	說明
uid	int	下屬的用戶ID
name	string	下屬的用戶名
position	string	下屬的崗位

​請求失敗參數說明

參數名	類型	說明
code	Int	響應狀態碼非1值
msg	string	錯誤提示信息

code值說明

Code	說明
1	成功
2	該人已經離職
3	請求參數不完整
4	參數類型錯誤

樣例：

​ 請求參數 uid 1

# 請求成功樣例
{    
    'code': 1,
    'msg': 'ok',
    'data':[
        {
        'uid':2,
        'name': 'Tom',
        'position': '教師'
        },
        {
        'uid':3,
        'name’: 'Lucy',
        'position': '助教'
        }
    ]
}

# 請求失敗樣例
    {
        'data': 2,
        'msg': '該人已離職'
}

10-django——RESTful API 之序列化