RESTful/CRUD api

更新日期: 2018-01-26 阅读次数: 13363 分类: RESTful

Keep it simple, stupid. -- K.I.S.S

RESTful 与 CRUD 区别是什么

  • CRUD 定义了四个基本的数据操作:CREATE, READ, UPDATE, DELETE
  • RESTful 则是架构层的概念,包含了 CRUD 的理念。使用唯一的 URI 来标识要操作的资源。

URL

以 todos 为例

  • /todos
    • GET -> 批量获取
    • POST -> 创建一条新的 todo
  • /todos/(\d+)
    • GET -> 获取一条 todo
    • PUT -> 更新一条 todo
    • DELETE -> 删除一条 todo

如何让 RESTful api 与普通的返回 HTML 的 URL 名字区分开

  • RESTful api 的 URL 全部以 api 开头,例如 /api/todos
  • 返回 HTML 的 URL 则不需要加 api 前缀,例如 /todos

Response Format

use json

如何表示错误类型? HTTP 状态码还是单独的 json 字段?

比如一条插入操作,如何让前端知道插入成功了。如果使用 HTTP 状态码,返回 200 表 示成功,看起来很合理。但是,如果你访问了错误的 URL,通常对方返回的也是 200. 问题就出现了。所以还是使用自己的一套错误码比较靠谱。

返回码

参考腾讯开放平台 API 的设计,采用二级错误码机制

  • ret: 公共返回码
    • ret=0, 成功返回
    • ret=1, 参数错误
    • ret=2, 频率受限
    • ret=3, 鉴权失败
    • ret=4, 服务器内部错误
    • ret=5, 用户错误
    • ret=7, 未实名认证
  • errcode: 二级错误码 (小应用可以不使用)
    • 以 ret=1 为例,errcode=260000,error content len (内容长度错误,超出140字或为空)
  • msg: 错误信息
    • ret=0, errcode=0, msg="ok"
    • ret=1, errcode=260000, msg="error content len"
  • data: 有用的数据

参考

关于作者 🌱

我是来自山东烟台的一名开发者,有敢兴趣的话题,或者软件开发需求,欢迎加微信 zhongwei 聊聊, 查看更多联系方式