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

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

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

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

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

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

版本：

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

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

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

獲取所有學(xué)生：

https://www.sunck.wang/api/v1... 錯(cuò)誤寫法

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

使用正確的HTTP請(qǐng)求方法

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

例子

描述	方式
列出所有班級(jí)	GET /grades/
獲取某個(gè)指定班級(jí)編號(hào)的信息	GET /grades/id
列出某個(gè)指定編號(hào)的班級(jí)的所有學(xué)生	GET /grades/id/students/
獲取某個(gè)指定編號(hào)的學(xué)生信息	GET /students/id
創(chuàng)建一個(gè)學(xué)生	POST /students/
更新某個(gè)指定學(xué)生的信息(信息全部由客戶端提供)	PUT /students/id
刪除某個(gè)指定編號(hào)的學(xué)生	DELETE /students/id
刪除某個(gè)指定班級(jí)的下的所有學(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é)果按照哪個(gè)屬性排序，以及排序的順序	GET /students/?sortby=&order=
指定篩選條件	GET /students/?student_age_gt=

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

狀態(tài)碼

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

錯(cuò)誤處理

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

{
    error:"Invalid API KEY",
}

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

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

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

使用鏈接相關(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：表示這個(gè)API與當(dāng)前網(wǎng)址的關(guān)系

href：表示API路徑

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

type：表示返回的類型

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

API文檔規(guī)范要求

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

二、請(qǐng)求的URL是什么

三、請(qǐng)求方式是什么（POST、GET、 DELETE、PUT、 PATCH等）

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

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

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

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

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

Demo：

? 功能：獲取某人的下屬

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

請(qǐng)求參數(shù)說明：

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

請(qǐng)求成功參數(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	下屬的崗位

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

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

code值說明

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

樣例：

? 請(qǐng)求參數(shù) uid 1

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

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

10-django——RESTful API 之序列化

云服務(wù)器 GPU云服務(wù)器設(shè)計(jì)風(fēng)格網(wǎng)站設(shè)計(jì)風(fēng)格 md設(shè)計(jì)風(fēng)格 REST

文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請(qǐng)注明本文地址：http://systransis.cn/yun/42023.html

發(fā)表評(píng)論

登陸后可評(píng)論

0條評(píng)論

scq000

男|高級(jí)講師

我要關(guān)注我要私信

TA的文章

SBT30100VDC-ASEMI低壓降肖特基二極管SBT30100VDC

閱讀 2379·2021-11-11 16:54
python-mqtt自動(dòng)化測試

閱讀 2631·2021-09-26 09:47
周文康的大一Python學(xué)習(xí)心得體會(huì)

閱讀 3992·2021-09-08 09:36
JimCloud-五一大促，香港美國物理機(jī)五折優(yōu)惠！400/月起 JimCloud云主機(jī)五折起!35

閱讀 2742·2021-07-25 21:37
WebWork（在主線程創(chuàng)建子進(jìn)程）

閱讀 934·2019-08-30 15:54
被遺忘的CSS

閱讀 2545·2019-08-30 14:22
教你實(shí)現(xiàn)首行及首列固定 Table

閱讀 3256·2019-08-30 13:57
如何解決滾動(dòng)條scrollbar出現(xiàn)造成的頁面寬度被擠壓的問題？

閱讀 2607·2019-08-29 17:17

成人国产在线小视频_日韩寡妇人妻调教在线播放_色成人www永久在线观看_2018国产精品久久_亚洲欧美高清在线30p_亚洲少妇综合一区_黄色在线播放国产_亚洲另类技巧小说校园_国产主播xx日韩_a级毛片在线免费

資訊專欄INFORMATION COLUMN

上云采購季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長期優(yōu)惠，快來選購！

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

相關(guān)文章

詳解REST架構(gòu)風(fēng)格

淺談REST風(fēng)格

那些年，我們一起誤解過的REST

RESTful實(shí)踐（具體應(yīng)用）思考

基于ThinkPHP 的Api 設(shè)計(jì)

發(fā)表評(píng)論

0條評(píng)論

scq000

男|高級(jí)講師

TA的文章

SBT30100VDC-ASEMI低壓降肖特基二極管SBT30100VDC

python-mqtt自動(dòng)化測試

周文康的大一Python學(xué)習(xí)心得體會(huì)

JimCloud-五一大促，香港美國物理機(jī)五折優(yōu)惠！400/月起 JimCloud云主機(jī)五折起!35

WebWork（在主線程創(chuàng)建子進(jìn)程）

被遺忘的CSS

教你實(shí)現(xiàn)首行及首列固定 Table

如何解決滾動(dòng)條scrollbar出現(xiàn)造成的頁面寬度被擠壓的問題？

最新活動(dòng)

資訊專欄INFORMATION COLUMN

上云采購季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長期優(yōu)惠，快來選購！

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

相關(guān)文章

發(fā)表評(píng)論

0條評(píng)論

男|高級(jí)講師

TA的文章

最新活動(dòng)

上云采購季！| 2核2G4M爆款云服務(wù)器低至59元/年，更有多臺(tái)、長期優(yōu)惠，快來選購！