简介

一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

主要原则

  • 网络上的所有事物都被抽象为资源
  • 每个资源都有一个唯一的资源标识符
  • 同一个资源具有多种表现形式(xml,json等)
  • 对资源的各种操作不会改变资源标识符
  • 所有的操作都是无状态的
  • 符合REST原则的架构方式即可称为RESTful

协议

用户与restful api之间的通信协议使用https协议

域名

restful api放在专门的域名下面：

https://restfulapi.com

或者放在主域名之下：

https://demo.com/api

版本

restful api版本应该体现在url中

https://restfulapi.com/v1/

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

  • GET（SELECT）：从服务器取出资源（一项或多项）。
  • POST（CREATE）：在服务器新建一个资源。
  • PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  • DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词。

  • HEAD：获取资源的元数据。
  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

关于方法的使用：

restful api_服务器

一些例子：

  • GET /users 获取所有的用户信息
  • GET /users/id 获取指定的用户信息
  • GET /users/id/cars 获取指定用户的所有车辆信息
  • POST /users 新增用户信息
  • PUT /users/id 更新指定的用户信息(全部更新)
  • PATCH /users/id 更新指定的用户信息(部分更新)
  • DELETE /users/id 删除指定用户信息
  • DELETE /users/id/cars/id 删除指定用户的指定车辆

过滤

对返回的结果进行数据过滤，下面是一些常用参数

  • ?limit=10 设置返回的数据数量
  • ?offset=10 设置返回数据的起始位置
  • ?page=1&size=10 设置分页，当前页数和每页大小
  • ?sortby=age&order=asc 设置排序的标识以及升序或者降序

使用HTTP状态码处理错误

Http状态码提供70个出错，我们只要使用10个左右：

  • 200 – OK – 一切正常
  • 201 – OK – 新的资源已经成功创建
  • 204 – OK – 资源已经成功删除
  • 304 – Not Modified – 客户端使用缓存数据
  • 400 – Bad Request – 请求无效，需要附加细节解释如 “JSON无效”
  • 401 – Unauthorized – 请求需要用户验证
  • 403 – Forbidden – 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。
  • 404 – Not found – 没有发现该资源
  • 422 – Unprocessable Entity – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。
  • 500 – Internal Server Error – API开发者应该避免这种错误。

注意

  1. API的身份认证应该使用OAuth 2.0框架。
  2. 服务器返回的数据格式，应该尽量使用JSON，避免使用XML。

登录restful api设计

用户登录可以理解为获取授权
PC端登录api设计

  • GET /session

移动端登录api设计

  • GET /token

建议：​​10个有关RESTful API良好设计的最佳实践​​