[點(diǎn)晴永久免費(fèi)OA]RESTful API設(shè)計(jì)規(guī)范
該倉庫整理了目前比較流行的 Table of Contents
關(guān)于「能愿動詞」的使用為了避免歧義，文檔大量使用了「能愿動詞」，對應(yīng)的解釋如下：
參見：RFC 2119 Protocol客戶端在通過 API Root URL
如果你的應(yīng)用很龐大或者你預(yù)計(jì)它將會變的很龐大，那 Versioning所有的 目前比較常見的兩種版本號形式： 在 URL 中嵌入版本編號api.example.com/v1/* 這種做法是版本號直觀、易于調(diào)試；另一種做法是，將版本號放在 通過媒體類型來指定版本信息Accept: application/vnd.example.com.v1+json 其中
后面幾個(gè)參數(shù)依次為應(yīng)用名稱（一般為應(yīng)用域名）、版本號、期望的返回格式。 至于具體把版本號放在什么地方，這個(gè)問題一直存在很大的爭議，但由于我們大多數(shù)時(shí)間都在使用 Endpoints端點(diǎn)就是指向特定資源或資源集合的
至于 URL 是否必須使用連字符（ 來看一個(gè)反例
再來看一個(gè)正列
HTTP 動詞對于資源的具體操作類型，由
其中 1 刪除資源 針對每一個(gè)端點(diǎn)來說，下面列出所有可行的
超出 Filtering如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API
所有 分頁參數(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
}客戶端在請求需要認(rèn)證的 Authorization: Bearer token... 當(dāng)超過指定的秒數(shù)后， HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_token"
}Laravel 開發(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": "該活動不存在",
}下表列舉了常見的
只有來自客戶端的請求被正確的處理后才能返回 必須強(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": "供開發(fā)者查看的錯(cuò)誤信息",
"debug": [
"錯(cuò)誤堆棧，必須開啟 debug 才存在"
]
}下面詳細(xì)列舉了各種情況 API 的返回說明。 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"
}
}
}
}其中，分頁和其他額外的媒體信息，必須放到 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)接受到了來自客戶端的請求，但還未開始處理。常用短信發(fā)送、郵件通知、模板消息推送等這類很耗時(shí)需要隊(duì)列支持的場景中； 返回該狀態(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ò)誤（例如，請求語法格式錯(cuò)誤、無效的請求、無效的簽名等），服務(wù)器 當(dāng)服務(wù)器無法從其他 4xx 類型的狀態(tà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":"無效的簽名"}401 Unauthorized該狀態(tài)碼表示當(dā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)碼可以簡單的理解為沒有權(quán)限訪問該請求，服務(wù)器收到請求但拒絕提供服務(wù)。 如當(dā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)碼表示用戶請求的資源不存在，如
都 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é)議一般通過請求首部的 Accept 來指定數(shù)據(jù)格式 408 Request Timeout客戶端請求超時(shí)時(shí) 409 Confilct該狀態(tài)碼表示因?yàn)檎埱蟠嬖跊_突無法處理。如通過手機(jī)號碼提供注冊功能的 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ī)號已存在"}410 Gone和 413 Request Entity Too Large該狀態(tài)碼表示服務(wù)器拒絕處理當(dāng)前請求，因?yàn)樵撜埱筇峤坏膶?shí)體數(shù)據(jù)大小超過了服務(wù)器愿意或者能夠處理的范圍。 此種情況下，服務(wù)器可以關(guān)閉連接以免客戶端繼續(xù)發(fā)送此請求。 如果這個(gè)狀況是臨時(shí)的，服務(wù)器 414 Request-URI Too Long該狀態(tài)碼表示請求的 415 Unsupported Media Type通常表示服務(wù)器不支持客戶端請求首部 該狀態(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)碼表示用戶請求次數(shù)超過允許范圍。如 X-RateLimit-Limit: 10 請求速率（由應(yīng)用設(shè)定，其單位一般為小時(shí)/分鐘等，這里是 10次/5分鐘） X-RateLimit-Remaining: 0 當(dāng)前剩余的請求數(shù)量 X-RateLimit-Reset: 1529839462 重置時(shí)間 Retry-After: 120 下一次訪問應(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ān)鍵字查詢
相關(guān)文章
正在查詢... 
|
400 186 1886
