REST api 设计风格

1、什么是 REST 的设计风格

REST是一种面向资源URL设计风格,URL地址表示资源(也就是一个名词),而请求的方法对应对资源的操作,URL中不会出现动词,例如:

请求含义错误正确
获取所有小狗狗GET /rest/api/getDogsGET /rest/api/dogs
添加一个小狗狗GET /rest/api/addDogsPOST /rest/api/dogs
修改一个小狗狗GET /rest/api/editDogs/:dog_idPUT /rest/api/dogs/:dog_id
删除一个小狗狗GET /rest/api/deleteDogs/:dog_idDELETE /rest/api/dogs/:dog_id

REST 的动词

对于crud四种任务,REST使用以下5种动词,对应不同的请求方法:

  • GET:取出资源
  • POST:新建资源
  • PUT:更新资源(提供完整的更新体)
  • PATCH:更新资源(只提供修改部分)
  • DELETE:删除资源

对于比较复杂的任务,Non-CRUD的操作,REST可以在路径上增加"action?action-id=XXX"的形式,对应 POST /资源/action作为URL,并将操作放在body体中。

优缺点:

  • 优点:容易理解
  • 缺点:设计变得比较复杂

2、路径规范:

  • 结尾不包含/:https://api.example.com/v1/hosts(正确)https://api.example.com/v1/hosts/(错误)
  • /用于指示层级关系
  • 连接符用-:例如:my-doc,不要使用_
  • 使用小写字母,因为有一些规范不区分大小写
  • 不要把扩展名放进路径,使用Content-Type传递格式

3、请求返回体

  • 返回容易理解的JSON体
  • 可以加入request-id标识请求的唯一性,方便追溯
  • 支持Etag缓存

4、错误处理

生成结构化的错误信息:
包含一个机器可读的错误 id,一个人类可读的错误信息(message),根据情况可以添加一个URL来告诉客户端关于这个错误的更多信息以及如何去解决它。

例如:

HTTP/1.1 501 Not Implemented

{

    "error_code": "XXS.0005",

    "error_msg": "Service does not exist"

}
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值