[點(diǎn)晴永久免費(fèi)OA]RESTful API設(shè)計(jì)規(guī)范
該倉(cāng)庫(kù)整理了目前比較流行的 Table of Contents
關(guān)于「能愿動(dòng)詞」的使用為了避免歧義，文檔大量使用了「能愿動(dòng)詞」，對(duì)應(yīng)的解釋如下：
參見(jiàn)：RFC 2119 Protocol客戶端在通過(guò) API Root URL
如果你的應(yīng)用很龐大或者你預(yù)計(jì)它將會(huì)變的很龐大，那 Versioning所有的 目前比較常見(jiàn)的兩種版本號(hào)形式： 在 URL 中嵌入版本編號(hào)api.example.com/v1/* 這種做法是版本號(hào)直觀、易于調(diào)試；另一種做法是，將版本號(hào)放在 通過(guò)媒體類型來(lái)指定版本信息Accept: application/vnd.example.com.v1+json 其中
后面幾個(gè)參數(shù)依次為應(yīng)用名稱（一般為應(yīng)用域名）、版本號(hào)、期望的返回格式。 至于具體把版本號(hào)放在什么地方，這個(gè)問(wèn)題一直存在很大的爭(zhēng)議，但由于我們大多數(shù)時(shí)間都在使用 Endpoints端點(diǎn)就是指向特定資源或資源集合的
至于 URL 是否必須使用連字符（ 來(lái)看一個(gè)反例
再來(lái)看一個(gè)正列
HTTP 動(dòng)詞對(duì)于資源的具體操作類型，由
其中 1 刪除資源 針對(duì)每一個(gè)端點(diǎn)來(lái)說(shuō)，下面列出所有可行的
超出 Filtering如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API
所有 分頁(yè)參數(shù) 經(jīng)常使用的、復(fù)雜的查詢 GET /trades?status=closed&sort=sortby=name&order=asc
# 可為其定制快捷方式
GET /trades/recently_closedAuthentication
Oauth 的端點(diǎn)設(shè)計(jì)示列
客戶端在獲得 {
"access_token": "token....",
"token_type": "Bearer",
"expires_in": 3600
}客戶端在請(qǐng)求需要認(rèn)證的 Authorization: Bearer token... 當(dāng)超過(guò)指定的秒數(shù)后， HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_token"
}Laravel 開(kāi)發(fā)中， Response所有的 HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"code": 0,
"msg": "success",
"data": {
"username": "username"
}
}或 HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"code": -1,
"msg": "該活動(dòng)不存在",
}下表列舉了常見(jiàn)的
只有來(lái)自客戶端的請(qǐng)求被正確的處理后才能返回 必須強(qiáng)調(diào)的是，所有 1、將錯(cuò)誤詳細(xì)放入 X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication2、直接放入響應(yīng)實(shí)體中； HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive
{"error_code":40100,"message":"Unauthorized"}考慮到易讀性和客戶端的易處理性，我們 {
"message": "您查找的資源不存在",
"error_code": 404001
}其中錯(cuò)誤碼（ HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:15:52 GMT
Connection: keep-alive
{"error_code":429001,"message":"你操作太頻繁了"}HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:19:27 GMT
Connection: keep-alive
{"error_code":403002,"message":"用戶已禁用"}
{
"message": "直接展示給終端用戶的錯(cuò)誤信息",
"error_code": "業(yè)務(wù)錯(cuò)誤碼",
"error": "供開(kāi)發(fā)者查看的錯(cuò)誤信息",
"debug": [
"錯(cuò)誤堆棧，必須開(kāi)啟 debug 才存在"
]
}下面詳細(xì)列舉了各種情況 API 的返回說(shuō)明。 200 ok
錯(cuò)誤示例： HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com
{
"user": {
"id":1,
"nickname":"fwest",
"username": "example"
}
}正確示例： 1、獲取單個(gè)資源詳情 {
"id": 1,
"username": "godruoyi",
"age": 88,
}2、獲取資源集合 [
{
"id": 1,
"username": "godruoyi",
"age": 88,
},
{
"id": 2,
"username": "foo",
"age": 88,
}
]3、額外的媒體信息 {
"data": [
{
"id": 1,
"avatar": "https://lorempixel.com/640/480/?32556",
"nickname": "fwest",
"last_logined_time": "2018-05-29 04:56:43",
"has_registed": true
},
{
"id": 2,
"avatar": "https://lorempixel.com/640/480/?86144",
"nickname": "zschowalter",
"last_logined_time": "2018-06-16 15:18:34",
"has_registed": true
}
],
"meta": {
"pagination": {
"total": 101,
"count": 2,
"per_page": 2,
"current_page": 1,
"total_pages": 51,
"links": {
"next": "http://api.example.com?page=2"
}
}
}
}其中，分頁(yè)和其他額外的媒體信息，必須放到 201 created當(dāng)服務(wù)器創(chuàng)建數(shù)據(jù)成功時(shí)，
等，都可以返回 HTTP/1.1 201 created
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:13:40 GMT
Connection: keep-alive
{
"id": 1,
"avatar": "https:\/\/lorempixel.com\/640\/480\/?32556",
"nickname": "fwest",
"last_logined_time": "2018-05-29 04:56:43",
"created_at": "2018-06-16 17:55:55",
"updated_at": "2018-06-16 17:55:55"
}也可以返回一個(gè)響應(yīng)實(shí)體為空的 HTTP/1.1 201 created
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:12:20 GMT
Connection: keep-alive這里我們 202 Accepted該狀態(tài)碼表示服務(wù)器已經(jīng)接受到了來(lái)自客戶端的請(qǐng)求，但還未開(kāi)始處理。常用短信發(fā)送、郵件通知、模板消息推送等這類很耗時(shí)需要隊(duì)列支持的場(chǎng)景中； 返回該狀態(tài)碼時(shí)，響應(yīng)實(shí)體 HTTP/1.1 202 Accepted Server: nginx/1.11.9 Content-Type: text/html; charset=UTF-8 Transfer-Encoding: chunked Date: Sun, 24 Jun 2018 09:25:15 GMT Connection: keep-alive 204 No Content該狀態(tài)碼表示響應(yīng)實(shí)體不包含任何數(shù)據(jù)，其中：
HTTP/1.1 204 No Content
Server: nginx/1.11.9
Date: Sun, 24 Jun 2018 09:29:12 GMT
Connection: keep-alive3xx 重定向所有 HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 09:41:50 GMT
Location: https://example.com
Connection: keep-alive
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<meta http-equiv="refresh" content="0;url=https://example.com" />
<title>Redirecting to https://example.com</title>
</head>
<body>
Redirecting to <a href="https://example.com">https://example.com</a>.
</body>
</html>所有 HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:52:50 GMT
Location: https://godruoyi.com
Connection: keep-alive400 Bad Request由于明顯的客戶端錯(cuò)誤（例如，請(qǐng)求語(yǔ)法格式錯(cuò)誤、無(wú)效的請(qǐng)求、無(wú)效的簽名等），服務(wù)器 當(dāng)服務(wù)器無(wú)法從其他 4xx 類型的狀態(tài)碼中找出合適的來(lái)表示錯(cuò)誤類型時(shí)，都 HTTP/1.1 400 Bad Request
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:22:36 GMT
Connection: keep-alive
{"error_code":40000,"message":"無(wú)效的簽名"}401 Unauthorized該狀態(tài)碼表示當(dāng)前請(qǐng)求需要身份認(rèn)證，以下情況都
客戶端在收到 HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
WWW-Authenticate: JWTAuth
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:17:02 GMT
Connection: keep-alive
{"message":"Token Signature could not be verified.","error_code": "40100"}403 Forbidden該狀態(tài)碼可以簡(jiǎn)單的理解為沒(méi)有權(quán)限訪問(wèn)該請(qǐng)求，服務(wù)器收到請(qǐng)求但拒絕提供服務(wù)。 如當(dāng)普通用戶請(qǐng)求操作管理員用戶時(shí)， HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:05:34 GMT
Connection: keep-alive
{"error_code":40301,"message":"權(quán)限不足"}404 Not Found該狀態(tài)碼表示用戶請(qǐng)求的資源不存在，如
都 405 Method Not Allowed當(dāng)客戶端使用的 如客戶端調(diào)用了 該響應(yīng) HTTP/1.1 405 Method Not Allowed
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Allow: GET, HEAD
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:30:57 GMT
Connection: keep-alive
{"message":"405 Method Not Allowed","error_code": 40500}406 Not Acceptable
Http 協(xié)議一般通過(guò)請(qǐng)求首部的 Accept 來(lái)指定數(shù)據(jù)格式 408 Request Timeout客戶端請(qǐng)求超時(shí)時(shí) 409 Confilct該狀態(tài)碼表示因?yàn)檎?qǐng)求存在沖突無(wú)法處理。如通過(guò)手機(jī)號(hào)碼提供注冊(cè)功能的 HTTP/1.1 409 Conflict
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:19:04 GMT
Connection: keep-alive
{"error_code":40900,"message":"手機(jī)號(hào)已存在"}410 Gone和 413 Request Entity Too Large該狀態(tài)碼表示服務(wù)器拒絕處理當(dāng)前請(qǐng)求，因?yàn)樵撜?qǐng)求提交的實(shí)體數(shù)據(jù)大小超過(guò)了服務(wù)器愿意或者能夠處理的范圍。 此種情況下，服務(wù)器可以關(guān)閉連接以免客戶端繼續(xù)發(fā)送此請(qǐng)求。 如果這個(gè)狀況是臨時(shí)的，服務(wù)器 414 Request-URI Too Long該狀態(tài)碼表示請(qǐng)求的 415 Unsupported Media Type通常表示服務(wù)器不支持客戶端請(qǐng)求首部 該狀態(tài)碼也可用于如：只允許上傳圖片格式的文件，但是客戶端提交媒體文件非法或不是圖片類型，這時(shí) HTTP/1.1 415 Unsupported Media Type
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:09:40 GMT
Connection: keep-alive
{"error_code":41500,"message":"不允許上傳的圖片格式"}429 Too Many Requests該狀態(tài)碼表示用戶請(qǐng)求次數(shù)超過(guò)允許范圍。如 X-RateLimit-Limit: 10 請(qǐng)求速率（由應(yīng)用設(shè)定，其單位一般為小時(shí)/分鐘等，這里是 10次/5分鐘） X-RateLimit-Remaining: 0 當(dāng)前剩余的請(qǐng)求數(shù)量 X-RateLimit-Reset: 1529839462 重置時(shí)間 Retry-After: 120 下一次訪問(wèn)應(yīng)該等待的時(shí)間（秒） 列子 HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1529839462
Retry-After: 290
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 11:19:32 GMT
Connection: keep-alive
{"message":"You have exceeded your rate limit.","error_code":42900}
500 Internal Server Error該狀態(tài)碼 503 Service Unavailable該狀態(tài)碼表示服務(wù)器暫時(shí)處理不可用狀態(tài)，當(dāng)服務(wù)器需要維護(hù)或第三方 HTTP/1.1 503 Service Unavailable
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:56:20 GMT
Retry-After: 60
Connection: keep-alive
{"error_code":50300,"message":"服務(wù)維護(hù)中"}其他 版權(quán)聲明版權(quán)聲明：自由轉(zhuǎn)載-非商用-非衍生-保持署名（創(chuàng)意共享3.0許可證） 建議參考Principles of good RESTful API Design（譯） LICENSEMIT License Copyright (c) 2018 godruoyi Permission is hereby granted, free of charge, to any person obtaining a copy The above copyright notice and this permission notice shall be included in all THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 該文章在 2022/4/18 18:07:11 編輯過(guò) |
關(guān)鍵字查詢
相關(guān)文章
正在查詢... 
|
400 186 1886
