RESTful/CRUD api

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: 有用的数据
  

参考

• RESTful
  
• Create, read, update and delete
  

关于作者 🌱

我是来自山东烟台的一名开发者，有感兴趣的话题，或者软件开发需求，欢迎加微信 zhongwei 聊聊，或者关注我的个人公众号“大象工具”， 查看更多联系方式