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 | 删除资源 | 是 |
Q.E.D.
Comments | 0 条评论