restful api

简介

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

主要原则

• 网络上的所有事物都被抽象为资源
• 每个资源都有一个唯一的资源标识符
• 同一个资源具有多种表现形式(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：获取信息，关于资源的哪些属性是客户端可以改变的。

关于方法的使用：

一些例子：

• 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良好设计的最佳实践