php restful规范,RESTFul API规范 详细指南

RESTFul规范

RESTFul是一种HTTP API接口规范，只要满足的RESTFul规范，即可称为RESTFul API。

既然是接口，我们先来了解一下，他和传统的API接口有何不同吧。

本文以尽量简单明了的文字来介绍、描述，只讲核心内容，仅供入门指引。

1 与传统API的区别

RESTFul世界中，一切皆抽象为资源(Resource)。

用户是资源，文章是资源、评论是资源，抽象一点的session、token等均是资源。

下面例子，我们通过以下几个常用的HTTP方法对资源(图书)进行操作。

RESTFul中：

操作 方法 示例

查询 GET GET /books

增加 POST POST /books

修改 PUT PUT /books

删除 DELETE DELETE /books

传统API中：

操作 方法 示例

查询 GET GET /api/book/getBook

增加 POST POST /api/book/addBook

修改 POST POST /api/book/updateBook

删除 GET/POST POST /api/book/deleteBook

2 URL设计

RESTFul API规范很简单，关键只需满足这一点。

动词(HTTP动作) + 名词(资源)

2.1 常用动作

通常我们采用以下5种 HTTP方法(动作)。

GET：查询(Read)

POST：增加(Create)

PUT：更新(Update)

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

DELETE：删除(Delete)

2.2 名词尽量复数

名词尽量采用复数(语义更明确，但并不强制)，举个例子：

类型 操作 示例

单数 获取所有图书 GET /book

单数 获取ID为1的图书 GET /book/1

复数 获取所有图书 GET /books

复数 获取ID为1的图书 GET /books/1

不难发现，复数形式语义更明确。

2.3 方法 & 过滤参数

方法应当以路径(path)的方式传递：

示例：

获取部门：GET /departments

获取部门下的所有员工：GET /departments/{id}/employees

获取部门下的某个员工：GET /departments/{id}/employees/{id}

文章点赞：PUT /articles/{id}/praise

过滤参数应当以查询字符串(QueryString)的方式传递：

示例：

获取第1页，每页显示10条：GET /books?page=1&per_page=10

获取已经发布的文章：GET /articles?published=true(或等于1也行)

何时使用方法，何时使用过滤参数？

区别：

方法：获取后的数据结构不同了。

过滤参数：获取后的数据结构还是一样的，只是数量减少了。

3 响应请求

必须尽可能返回意义准确的HTTP状态码，不要一味的返回200状态码。

状态码主要分为5类：

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

1XX：信息类

2XX：成功类

3XX：重定向

4XX：客户端错误

5XX：服务器错误

有关状态码的详细参考：HTTP状态码

常用HTTP状态码：

响应码 说明

200 OK 请求已成功

201 Created 资源已创建

204 No Content 请求已成功，但无返回内容

304 Not Modified 缓存有效

400 Bad Request 语义有误，当前请求无法被服务器理解，请求参数错误

401 Unauthorized 当前请求需要用户认证(登录)

403 Forbidden 用户已认证(登录)，但权限不足

404 Not Found 请求源未在服务器上被发现

405 Method Not Allowed 请求方法不能被用于请求相应的资源，如使用PUT方法访问只接受POST方法的API

500 Internal Server Error 服务端内部错误

502 Bad Gateway 网关错误

504 Gateway Timeout 网关超时

3.1 成功类

对于成功类，除了GET请求需要返回响应体(数据)之外，其他请求均可不返回响应体。

获取文章：

返回200状态码，返回的数据不需要进行多余的包装。

GET /articles/1

HTTP/1.1 200 OK

{"title": "文章标题",

"content": "文章内容"

}

增加文章：

返回201状态码，可选返回响应体(创建后的对象)。

POST /articles

HTTP/1.1 201 Created

{"id": 1,

"title": "文章标题",

"content": "文章内容"

}

HTTP/1.1 201 Created

更新文章：

若返回响应体(更新后的对象)则使用200状态码，否则使用204状态码。

PUT /articles/1

HTTP/1.1 200 OK

{"id": 1,

"title": "文章标题",

"content": "文章内容"

}

HTTP/1.1 204 No Content

删除文章：

返回204状态码。

DELETE /articles/1

HTTP/1.1 204 No Content

3.2 错误类

建议为所有错误的请求响应体加上错误代码、消息字段。

错误代码建议由HTTP状态码 + 自定义的错误代码组成。

例如：客户端错误状态码为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": "用户未登录"

}

权限不足：

HTTP/1.1 403 Forbidden

{"error_code": 40301,

"message": "权限不足"

}

文章不存在或已被删除：

HTTP/1.1 404 Not Found

{"error_code": 40401,

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

}

3.2.2 服务器错误

HTTP/1.1 500 Internal Server Error

{"error_code": 50001,

"message": "服务器内部错误，请稍后再试或联系管理员"

}

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

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

以上转自：www.jianshu.com/p/843a524dd88f 作者：izhouteng

更多阅读资料：

REST API手册

WordPress Rest API 最细接口详解