9-django——restful設(shè)計風(fēng)格

scq000 發(fā)布于2019-07-30 17:07 / 815人閱讀

摘要：設(shè)計風(fēng)格協(xié)議與用戶的通信協(xié)議，總是使用協(xié)議域名應(yīng)該盡量將部署在專用域名之下，如果確定很簡單，不會有進(jìn)一步的擴(kuò)展，可以考慮放在主域名之下。數(shù)據(jù)庫中的表示記錄同種數(shù)據(jù)的集合，所以中的名詞也應(yīng)該使用復(fù)數(shù)。

RESTful Api設(shè)計風(fēng)格

協(xié)議：API與用戶的通信協(xié)議，總是使用HTTPS協(xié)議

域名：應(yīng)該盡量將API部署在專用域名之下，如果確定API很簡單，不會有進(jìn)一步的擴(kuò)展，可以考慮放在主域名之下。

版本：

應(yīng)該將API的版本放在URL中：https://www.sunck.wang/api/v1.0

將版本號放在HTTP頭信息中：https://www.sunck.wang/students

路徑：表示API的具體網(wǎng)址，每個網(wǎng)址代表一種資源，所以網(wǎng)址中不能有動詞，只能有名詞，并且所用的名詞往往與數(shù)據(jù)庫的表名對應(yīng)。數(shù)據(jù)庫中的表示記錄同種數(shù)據(jù)的集合，所以API中的名詞也應(yīng)該使用復(fù)數(shù)。

獲取所有學(xué)生：

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

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

使用正確的HTTP請求方法

方式	解釋
GET select	從服務(wù)器獲取資源(一項或者多項)
POST create	在服務(wù)器新建一個資源
PUT update	在服務(wù)器更新資源(客戶端提供改變后的完整資源)
PATCH update	在服務(wù)器更新資源(客戶端提供改的屬性)
DELETE delete	從服務(wù)器刪除資源
HEAD	獲取資源的元數(shù)據(jù)
OPTIONS	獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的

例子

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

過濾信息

如果資源數(shù)較多，服務(wù)器不能將所有數(shù)據(jù)一次全部返回給客戶端，API應(yīng)該提供參數(shù)，過濾返回結(jié)果

例子

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

注意：參數(shù)的設(shè)計允許存在冗余，即允許API路徑和URL參數(shù)偶爾有重復(fù)

狀態(tài)碼

服務(wù)器向客戶端返回的狀態(tài)碼和提示信息

錯誤處理

如果錯誤碼是4xx，就應(yīng)該向用戶返回錯誤信息，一般來說，返回的信息中將error作為鍵名，出錯的信息作為鍵值即可

{
    error:"Invalid API KEY",
}

響應(yīng)結(jié)果

針對不同的操作，服務(wù)器向用戶返回結(jié)果應(yīng)該符合規(guī)范

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

使用鏈接相關(guān)的資源

返回結(jié)果中提供了鏈接，鏈向了其他的API方法，使得用戶不查看文檔，也知道下一步應(yīng)該做什么

示例

{
    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與當(dāng)前網(wǎng)址的關(guān)系

href：表示API路徑

title：表示API的標(biāo)題

type：表示返回的類型

其他：服務(wù)器返回的數(shù)據(jù)盡量使用JSON格式，避免使用XML格式

API文檔規(guī)范要求

一、寫明該接口的功能是什么

二、請求的URL是什么

三、請求方式是什么（POST、GET、 DELETE、PUT、 PATCH等）

四、參數(shù)是什么，此處還需說明你的參數(shù)名、參數(shù)類型、是否必填、參數(shù)的簡單解釋

五、請求成功時的響應(yīng)內(nèi)容（實際開發(fā)中，要與前端同事溝通使用什么樣的數(shù)據(jù)結(jié)構(gòu)），并且對其中的字段做出說明（包括含義、數(shù)據(jù)類型，數(shù)據(jù)結(jié)構(gòu)<字符串，數(shù)組，字典等>）

六、請求失敗時的響應(yīng)內(nèi)容，并且對其中的字段做出說明（包括含義、數(shù)據(jù)類型，數(shù)據(jù)結(jié)構(gòu)<字符串，數(shù)組，字典等>）包括多帶帶的對錯誤碼的說明

七、請求樣例（返回結(jié)果部分要包括成功的情況和失敗的情況）

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

Demo：

? 功能：獲取某人的下屬

? URL：”people/api/v1/ subordinate”

請求參數(shù)說明：

參數(shù)名	類型	是否必填	備注
uid	int	是	用戶的id

請求成功參數(shù)說明

參數(shù)名	類型	說明
code	Int	響應(yīng)狀態(tài)碼1代表成功
msg	string	響應(yīng)信息
data	數(shù)組	數(shù)組內(nèi)是字典類型，詳情見下表

data內(nèi)的響應(yīng)參數(shù)說明

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

?請求失敗參數(shù)說明

參數(shù)名	類型	說明
code	Int	響應(yīng)狀態(tài)碼非1值
msg	string	錯誤提示信息

code值說明

Code	說明
1	成功
2	該人已經(jīng)離職
3	請求參數(shù)不完整
4	參數(shù)類型錯誤

樣例：

? 請求參數(shù) uid 1

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

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

10-django——RESTful API 之序列化