RESTful API 设计规范

一个架构符合REST(REpresentational State Transfer)原则，就称它为RESTful架构。

资源 （Resources）

URI (Uniform Resource Identifiers) 统一资源标示符

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

URI规范：

• URI不包含动词，使用名词复数。
• URI不使用大写。
• URI层级不要太深。

URL(Uniform Resource Locator) 统一资源定位符(URI的实现)

对于REST API来说一个资源对应一个唯一的URI(URL)

表现（Representation）

HTTP请求的头信息中，用Accept和Content-Type标示。

状态转化（State Transfer）

• GET：获取资源
  GET /zoos
  GET /zoos/1
  GET /zoos/1/employees
  GET /zoos/1/employeessortby=name&order=asc

• POST：新建资源（也可以更新资源）
  POST /animals 新增动物
  POST /zoos/1/employees 新增动物园1雇员

• PUT：更新单个资源 全量更新
  PUT /animals/1
  PUT /zoos/1

• DELETE：删除资源
  DELETE /zoos/1/animals //删除id为1的动物园内的所有动物

常见异常返回码

• 400 bad request 常用在参数校验
• 401 unauthorized 未经验证的用户，常见于未登录。如果经过验证后依然没权限，应该 403（即 authentication 和 authorization 的区别）。
• 403 forbidden 无权限
• 404 not found 资源不存在
• 500 internal server error 代码逻辑错误导致，比如数据库连接失败、空指针异常、除0错误

异步任务

由于互联网通信 高延时（high latency）、高并发等特点 异步任务派上大用场。

1. 先返回任务创建成功
2. 客户端轮询任务状态

规范是提高效率的利器