Go Engineering - Foundation - API - RESTful
概述
- REST:Representational state transfer
- REST 只是一种软件架构风格,是一组架构约束条件和原则,而不是技术框架
- REST 有一系列规范,满足这些规范的 API 均可称为 RESTful API
- REST 规范把所有内容都视为资源,对资源的操作对应 HTTP 协议提供的 GET、POST、PUT 和 DELETE 方法
- 由于 REST 与 HTTP 协议相辅相成,因此 HTTP 协议已经成为 RESTful API 的事实标准
特点
- 以资源为中心,一切都可以抽象成资源,所有行为都是对资源的 CRUD
- 资源对应着面向对象范式里面的对象
- 资源使用 URI 标识,每个资源实例都有一个唯一的 URI 标识
- 资源是有状态的,使用 JSON/XML 等在 HTTP Body 里表征资源的状态
- 客户端通过 HTTP Method 对资源进行操作,实现 REST
- 无状态:每个 RESTful API 请求都包含了所有足够完成本次操作的信息,服务器无需保持 Session
- 无状态对于服务端的弹性扩容是很重要的
设计原则
RESTful API 的核心是规范
URI 设计
- 资源名使用名词复数,资源分为 Collection 和 Member 两种
- Collection:一堆资源的集合,如
https://iam.api.marmotedu.com/users
- Member:单个特定资源,如
https://iam.api.marmotedu/users/admin
- Collection:一堆资源的集合,如
- URI 结尾不应该包含
/
- URI 中不能出现
_
,统一使用-
– 脊柱命名法 - URI 路径使用小写
- 避免层级过深的 URI,如果超过 2 级,建议将其他资源转化为
?
参数- 不推荐:
/schools/tsinghua/classes/rooma/students/zhang
- 推荐:
/students?school=qinghua&class=rooma
- 不推荐:
- 某些情况,不好将操作映射为一个 REST 资源,可参考
- 将一个操作变成资源的属性,如
/users/zhangsan?active=false
- 将一个操作当作资源的嵌套资源,如
PUT /gists/:id/star
和DELETE /gists/:id/star
- 最后实在不行,可以不遵守这类规范,如
/login
- 将一个操作变成资源的属性,如
CRUD -> HTTP Method
使用 HTTP 协议原生的 GET、PUT(修改)、POST(新建) 和 DELETE 来标识对资源的 CRUD 操作
安全性:不会改变资源状态,即只读;幂等性:执行 1 次和执行 N 次,对资源状态改变的效果是等价的
- GET 返回的结果,要尽量可用于 PUT、POST 操作,保证信息的一致性
- 对资源进行状态或者属性的变更,要用 PUT 方法,POST 方法用于新建
- 批量删除,推荐使用
DELETE /users?ids=1,2,3
统一的返回格式
降低用户的心智负担:每个 RESTful API 的返回格式、错误和正确消息的返回格式,都应该保持一致
API 版本管理
位置 | 样例 | 备注 |
---|---|---|
URL | /v1/users |
推荐 |
Header | Accept: vnd.example-com.foo+json; version=1.0 |
|
Form | /users?version=v1 |
API 命名
命名方式 | 样例 | 备注 |
---|---|---|
驼峰命名法 | serverAddress | |
蛇形命名法 | server_address | |
脊柱命名法 | server-address | 推荐 |
统一:分页、过滤、排序、搜索
REST 资源的查询接口,都需要实现分页、过滤、排序、搜索功能,可实现为公共的 API 组件
功能 | 备注 |
---|---|
分页 | /users?offset=0&limit=20 |
过滤 | /users?fields=email,username,address |
排序 | /users?sort=age,desc |
搜索 | 模糊匹配,等同于垂直过滤 |
域名
命名方式 | 适用场景 |
---|---|
https://marmotedu.com/api | API 将来不会有进一步的扩展 |
https://iam.api.marmotedu.com | 使用专用的 API 域名,便于扩展,如 storage.api.marmotedu.com |
https://blog.zhongmingmao.top/2022/04/16/cloud-native-foundation-go-engineering-foundation-api-rest/
All articles in this blog are licensed under CC BY-NC-SA 4.0 unless stating additionally.