RESTful规范笔记

发表于 | 分类于

ResultFul的接口风格最近几年非常流行，本文记录阅读资料过程中学习的规范

HTTP Methods

enter image description here
其中 HEAD，TRACE，OPTIONS，CONNECT 在 RESTful API 设计中不常用

HTTP Status

  • 当GET, PUT和PATCH请求成功时，要返回对应的数据，及状态码200，即SUCCESS
  • 当POST创建数据成功时，要返回创建的数据，及状态码201，即CREATED
  • 当DELETE删除数据成功时，不返回数据，状态码要返回204，即NO CONTENT
  • 当GET不到数据时，状态码要返回404，即NOT FOUND
  • 任何时候，如果请求有问题，如校验请求数据时发现错误，要返回状态码400，即BAD REQUEST
  • 当API 请求需要用户认证时，如果request中的认证信息不正确，要返回状态码401，即NOT AUTHORIZED
  • 当API 请求需要验证用户权限时，如果当前用户无相应权限，要返回状态码 403，即FORBIDDEN

Pagination

1
2
3
4
5
6
7
8
{
 "page": 1,            # 当前是第几页
 "pages": 10,          # 总共多少页
 "pageSize": 10,       # 每页多少数据
 "hasNext": true,      # 是否有下一页数据
 "hasPrev": false,     # 是否有前一页数据
 "total": 100          # 总共多少数据
}

Back forward Slash (/)

目前比较流行的API设计方案，通常建议url以 / 作为结尾，SpringMVC中若不带 / 则也会重定向至 / 上

1
2
http://api.kok.com/flowers/
http://api.kok.com/flowers

连接符 - 和 下划线 _

1
2
3
4
#Good
http://api.kok.com/featured-flowers/
#Bad
http://api.kok.com/featured_flowers/