admin

初尝RESTFul规范
初尝RESTFul规范RESTFul是一种HTTP API接口规范,只要满足的RESTFul规范,即可称为REST...
扫描右侧二维码阅读全文
24
2019/11

初尝RESTFul规范

初尝RESTFul规范

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

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

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

1 与传统API的区别

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

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

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

RESTFul中:

操作方法示例
查询GETGET /books
增加POSTPOST /books
修改PUTPUT /books
删除DELETEDELETE /books

传统API中:

操作方法示例
查询GETGET /api/book/getBook
增加POSTPOST /api/book/addBook
修改POSTPOST /api/book/updateBook
删除GET/POSTPOST /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": "服务器内部错误,请稍后再试或联系管理员"
}
Last modification:November 24th, 2019 at 01:52 am

Leave a Comment