# RESTful 是什么？ 一种软件架构，设计风格，全称为 **Representational State Transfer**，但并不是标准，只是风格，根据该风格开发的 api 也简洁、易管理。 # RESTful 有什么用？ 一套接口应该满足以下几点： - 安全可靠，高效，易扩展。 - 简单明了，可读性强，没有歧义。 - API 风格统一，调用规则，传入参数和返回数据有统一的标准。 RESTful 的设计理念基于 HTTP 协议，它是一种设计风格，没有规定一定如何实现，但是提供了很好的设计理念。 **风格的统一**，使得不需要过多的解释，就能让使用者明白该如何使用，同时也会有很多现成的工具来帮助我们实现 RESTful 风格的接口 # 设计原则 ### 一、HTTPS 防止数据在传输过程中被篡改和窃听。 ### 二、域名 将 api 请求接口与区分开，例如 ``` https://api.huasio.com // or https://www.huasio.com/api ``` ### 三、版本控制 随之时间的改变，项目api也肯定会有所更改，所以开发新版本的 api 得时候需要更好的管理 api 版本。 例如：将版本号直接加入 URL 中 ``` https://api.larabbs.com/v1 https://api.larabbs.com/v2 ``` 使用 HTTP 请求头的 Accept 字段进行区分 ``` https://api.larabbs.com/ Accept: application/prs.larabbs.v1+json Accept: application/prs.larabbs.v2+json ``` ### 四、URL 定位资源 在 RESUful 中，一切皆是资源，每一个 URL 就是一个资源。资源应该是名词，并且多数时候是复数。 ### 五、资源过滤 提供合理的参数，请求合适数据。 ### 六、状态码 HTTP 提供的状态码： * 200 OK - 对成功的 GET、PUT、PATCH 或 DELETE 操作进行响应。也可以被用在不创建新资源的 POST 操作上 * 201 Created - 对创建新资源的 POST 操作进行响应。应该带着指向新资源地址的 Location 头 * 202 Accepted - 服务器接受了请求，但是还未处理，响应中应该包含相应的指示信息，告诉客户端该去哪里查询关于本次请求的信息 * 204 No Content - 对不会返回响应体的成功请求进行响应（比如 DELETE 请求） * 304 Not Modified - HTTP缓存header生效的时候用 * 400 Bad Request - 请求异常，比如请求中的body无法解析 * 401 Unauthorized - 没有进行认证或者认证非法 * 403 Forbidden - 服务器已经理解请求，但是拒绝执行它 * 404 Not Found - 请求一个不存在的资源 * 405 Method Not Allowed - 所请求的 HTTP 方法不允许当前认证用户访问 * 410 Gone - 表示当前请求的资源不再可用。当调用老版本 API 的时候很有用 * 415 Unsupported Media Type - 如果请求中的内容类型是错误的 * 422 Unprocessable Entity - 用来表示校验错误 * 429 Too Many Requests - 由于请求频次达到上限而被拒绝访问 ### 七、调用频率 为避免攻击，以及恶意请求，应该对 ip 限制请求次数。到了阈值之后对 ip 禁止请求等一些处理。 ### 八、数据响应格式 一般常用的数据格式是 JSON，若需要 XML，需要在 Accept 头指定数据格式。 ### 九、编写文档 编写接口，当然得配备对应得文档，一般来说需要包含以下几点： * 包括每个接口的请求参数，每个参数的类型限制，是否必填，可选的值等。 * 响应结果的例子说明，包括响应结果中，每个参数的释义。 * 对于某一类接口，需要有尽量详细的文字说明，比如针对一些特定场景，接口应该如何调用。 ### 十、使用 HTTP 动词描述请求操作 HTTP 提供的一些动词操作，RESTful 也利用了这些动词。 术语：**幂等性**：意思就是，一次或多次访问同一个资源的数据一致性。 | 动词 | 描述 | 是否幂等 | | ------------ | ------------ | ------------ | | GET | 获取资源 | 是 | |POST | 创建资源 | 否 | |PUT | 更新资源，客户端提供完整的资源数据 | 是 | |PATCH | 更新资源，客户端提供部分的资源数据 | 否 | |DELETE | 删除资源 | 是 |