RESTful API 设计入门

目前前后端对接其实主要是面向 API 文档开发,而 API 的设计中,有一种 RESTful API 的设计,具有规范,从某一种角度,我觉得 RESTful API 可以很好的把后端 API 从繁杂的业务中抽象出来,更好地进行管理和编写,同时也具有良好的可读性。

对于一些现代化的 MVC 框架,在脚手架阶段可能就会自动生成 RESTful 风格的 Controller。

资源的拆分

路由中 URI 中的资源都是名词,即一个个实体,对于代码而言,可以看做一个个类到 URI 的映射,比如:

GET /repos/:owner/:repo/stargazers
GET /organizations

HTTP 动词

对于 RESTful API 中,常用的动词有以下几种:

GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。

PUT 和 PATCH 的区别主要在于更新整个资源还是更新局部资源。

版本

当 API 可能出现重大变更,无法向后兼容时,RESTful API 提供了版本花的概念,可以保证旧版和新版的 API 的使用,有三种方法存放版本号:

  • 在uri中放版本信息:GET /v1/users/1
  • Accept Header:Accept: application/json+v1
  • 自定义 Header:X-Api-Version: 1

没有版本号的 API 并不是一个好的 RESTful API(对不起我又设计了辣鸡的 API)。

过滤

API 应该提供一定的筛选条件,比如:

?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件

状态码

服务器返回的状态码应该复合 HTTP 的规范,比如:

200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。

返回 JSON

RESTful API 应该尽可能的返回 JSON,对于错误的请求,需要为用户提供错误的信息。

{
  "code": 1234,
  "message": "Something bad happened :-(",
  "description": "More details about the error here"
}

不进行无意义的包装

body 只需要直接返回数据,不需要进行包装比如:

{
  "success": true,
  "data": {"id":1,"name":"xiaotuan"},
}

不止于 RESTful

尽管 RESTful API 的设计规范清晰可读,但是针对一些特殊的需求,我们可能也不一定要强制遵守 RESTful API 的设计规范。比如批量删除,DELETE 在 HTTP 规范中是没有参数的,这就给批量删除接口带来了一定的麻烦,可以考虑改用 POST。

参考资料

植入部分

如果您觉得文章不错,可以通过赞助支持我。

如果您不希望打赏,也可以通过关闭广告屏蔽插件的形式帮助网站运作。

标签: 知识

已有 3 条评论

  1. 开发者头条

    感谢分享!已推荐到《开发者头条》:https://toutiao.io/posts/4jlhy3 欢迎点赞支持!
    欢迎订阅《全栈大道宽又长》https://toutiao.io/subject/77790

  2. VV

    谢谢姐姐~总算明白啦~~

  3. Jupiter

    好棒棒哦??

添加新评论