web API端点设计与请求的形式
《web API的设计与开发》第2章概览
- 端点的基本设计
- HTTP方法和端点
- API端点的设计
- 搜索与查询参数的设计
- 查询参数和路径的使用区别
端点的基本设计
- 短小便与输入的URL
- 人可以读懂的的URL
- 没有大小写混用的URL(一般标准的做法是全部使用小写)
- 修改方便的URL
- 不会暴露服务器架构的URL
- 规则统一的URL
HTTP方法和端点
方法示例:
方法名 | 说明 |
---|---|
GET | 获取资源 |
POST | 新增资源(新用户注册,发布新的新闻等) |
PUT | 更新已有资源(发送的数据替换原有的资源信息) |
DELETE | 删除资源 |
PATCH | 更新部分资源(更新原有资源中的部分信息) |
HEAD | 获取资源的元信息 |
API端点的设计
- 访问资源的端点设计的注意事项
- 使用名词的复数形式
- 注意所用的单词
- 不使用空格及需要编码的字符
- 使用连接符来连接多个单词
搜索与查询参数的设计
- 获取数据量和获取位置的查询参数(per_page=50&page=3/limit=50&offset=100)
- 使用相对位置存在的问题(更新频率高会导致数据偏差)
- 使用绝对位置来获取数据(指定某个ID之前/某个日期之前)
- 用于过滤的参数
在查询参数名里指定进行过滤的要素名称,并指定进行过滤的值,如果有多个要素,则需要全部指定
查询参数和路径的使用区别
- 是否是表示唯一资源所需的信息
- 是否可以省略