RESTFul規(guī)范

RESTFul是一種HTTP API接口規(guī)范，只要滿足的RESTFul規(guī)范，即可稱為RESTFul API。

既然是接口，我們先來了解一下，他和傳統(tǒng)的API接口有何不同吧。

本文以盡量簡單明了的文字來介紹、描述，只講核心內(nèi)容，僅供入門指引。

1 與傳統(tǒng)API的區(qū)別

RESTFul世界中，一切皆抽象為資源(Resource)。

用戶是資源，文章是資源、評論是資源，抽象一點的session、token等均是資源。

下面例子，我們通過以下幾個常用的HTTP方法對資源(圖書)進(jìn)行操作。

RESTFul中：

操作 方法 示例

查詢 GET GET /books

增加 POST POST /books

修改 PUT PUT /books

刪除 DELETE DELETE /books

傳統(tǒng)API中：

操作 方法 示例

查詢 GET GET /api/book/getBook

增加 POST POST /api/book/addBook

修改 POST POST /api/book/updateBook

刪除 GET/POST POST /api/book/deleteBook

2 URL設(shè)計

RESTFul API規(guī)范很簡單，關(guān)鍵只需滿足這一點。

動詞(HTTP動作) + 名詞(資源)

2.1 常用動作

通常我們采用以下5種 HTTP方法(動作)。

GET：查詢(Read)

POST：增加(Create)

PUT：更新(Update)

PATCH：部分更新，不常用(Update)

DELETE：刪除(Delete)

2.2 名詞盡量復(fù)數(shù)

名詞盡量采用復(fù)數(shù)(語義更明確，但并不強(qiáng)制)，舉個例子：

類型 操作 示例

單數(shù) 獲取所有圖書 GET /book

單數(shù) 獲取ID為1的圖書 GET /book/1

復(fù)數(shù) 獲取所有圖書 GET /books

復(fù)數(shù) 獲取ID為1的圖書 GET /books/1

不難發(fā)現(xiàn)，復(fù)數(shù)形式語義更明確。

2.3 方法 & 過濾參數(shù)

方法應(yīng)當(dāng)以路徑(path)的方式傳遞：

示例：

獲取部門：GET /departments

獲取部門下的所有員工：GET /departments/{id}/employees

獲取部門下的某個員工：GET /departments/{id}/employees/{id}

文章點贊：PUT /articles/{id}/praise

過濾參數(shù)應(yīng)當(dāng)以查詢字符串(QueryString)的方式傳遞：

示例：

獲取第1頁，每頁顯示10條：GET /books?page=1&per_page=10

獲取已經(jīng)發(fā)布的文章：GET /articles?published=true(或等于1也行)

何時使用方法，何時使用過濾參數(shù)？

區(qū)別：

方法：獲取后的數(shù)據(jù)結(jié)構(gòu)不同了。

過濾參數(shù)：獲取后的數(shù)據(jù)結(jié)構(gòu)還是一樣的，只是數(shù)量減少了。

3 響應(yīng)請求

必須盡可能返回意義準(zhǔn)確的HTTP狀態(tài)碼，不要一味的返回200狀態(tài)碼。

狀態(tài)碼主要分為5類：

在RESTFul中通常我們只需要用到2XX、4XX、5XX。

1XX：信息類

2XX：成功類

3XX：重定向

4XX：客戶端錯誤

5XX：服務(wù)器錯誤

有關(guān)狀態(tài)碼的詳細(xì)參考：HTTP狀態(tài)碼

常用HTTP狀態(tài)碼：

響應(yīng)碼 說明

200 OK 請求已成功

201 Created 資源已創(chuàng)建

204 No Content 請求已成功，但無返回內(nèi)容

304 Not Modified 緩存有效

400 Bad Request 語義有誤，當(dāng)前請求無法被服務(wù)器理解，請求參數(shù)錯誤

401 Unauthorized 當(dāng)前請求需要用戶認(rèn)證(登錄)

403 Forbidden 用戶已認(rèn)證(登錄)，但權(quán)限不足

404 Not Found 請求源未在服務(wù)器上被發(fā)現(xiàn)

405 Method Not Allowed 請求方法不能被用于請求相應(yīng)的資源，如使用PUT方法訪問只接受POST方法的API

500 Internal Server Error 服務(wù)端內(nèi)部錯誤

502 Bad Gateway 網(wǎng)關(guān)錯誤

504 Gateway Timeout 網(wǎng)關(guān)超時

3.1 成功類

對于成功類，除了GET請求需要返回響應(yīng)體(數(shù)據(jù))之外，其他請求均可不返回響應(yīng)體。

獲取文章：

返回200狀態(tài)碼，返回的數(shù)據(jù)不需要進(jìn)行多余的包裝。

GET /articles/1

HTTP/1.1 200 OK

{"title": "文章標(biāo)題",

"content": "文章內(nèi)容"

}

增加文章：

返回201狀態(tài)碼，可選返回響應(yīng)體(創(chuàng)建后的對象)。

POST /articles

HTTP/1.1 201 Created

{"id": 1,

"title": "文章標(biāo)題",

"content": "文章內(nèi)容"

}

HTTP/1.1 201 Created

更新文章：

若返回響應(yīng)體(更新后的對象)則使用200狀態(tài)碼，否則使用204狀態(tài)碼。

PUT /articles/1

HTTP/1.1 200 OK

{"id": 1,

"title": "文章標(biāo)題",

"content": "文章內(nèi)容"

}

HTTP/1.1 204 No Content

刪除文章：

返回204狀態(tài)碼。

DELETE /articles/1

HTTP/1.1 204 No Content

3.2 錯誤類

建議為所有錯誤的請求響應(yīng)體加上錯誤代碼、消息字段。

錯誤代碼建議由HTTP狀態(tài)碼 + 自定義的錯誤代碼組成。

例如：客戶端錯誤狀態(tài)碼為400，賬號或密碼錯誤代碼為01(自定義)，組成40001錯誤代碼。

3.2.1 客戶端錯誤

登錄失敗：

POST /tokens/login

HTTP/1.1 400 Bad Request

{"error_code": 40001,

"message": "用戶名或密碼錯誤"

}

用戶名已被注冊：

POST /users

HTTP/1.1 400 Bad Request

{"error_code": 40002,

"message": "用戶名已被注冊"

}

未登錄：

HTTP/1.1 401 Unauthorized

{"error_code": 40101,

"message": "用戶未登錄"

}

權(quán)限不足：

HTTP/1.1 403 Forbidden

{"error_code": 40301,

"message": "權(quán)限不足"

}

文章不存在或已被刪除：

HTTP/1.1 404 Not Found

{"error_code": 40401,

"message": "文章不存在或已被刪除"

}

3.2.2 服務(wù)器錯誤

HTTP/1.1 500 Internal Server Error

{"error_code": 50001,

"message": "服務(wù)器內(nèi)部錯誤，請稍后再試或聯(lián)系管理員"

}

wordpress rest api Reference

REST API Developer Endpoint Reference #REST API Developer Endpoint Reference

Resource Base Route

Posts /wp/v2/posts

Post Revisions /wp/v2/posts//revisions

Categories /wp/v2/categories

Tags /wp/v2/tags

Pages /wp/v2/pages

Page Revisions /wp/v2/pages//revisions

Comments /wp/v2/comments

Taxonomies /wp/v2/taxonomies

Media /wp/v2/media

Users /wp/v2/users

Post Types /wp/v2/types

Post Statuses /wp/v2/statuses

Settings /wp/v2/settings

Themes /wp/v2/themes

Search /wp/v2/search

Blocks /wp/v2/blocks

Block Revisions /wp/v2/blocks//autosaves/

Block Renderer /wp/v2/block-renderer

====================================================================

以上轉(zhuǎn)自：www.jianshu.com/p/843a524dd88f 作者：izhouteng

更多閱讀資料：

REST API手冊

WordPress Rest API 最細(xì)接口詳解

總結(jié)

以上是生活随笔為你收集整理的php restful规范,RESTFul API规范 详细指南的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。