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之前/某个日期之前)
• 用于过滤的参数
  在查询参数名里指定进行过滤的要素名称，并指定进行过滤的值，如果有多个要素，则需要全部指定

查询参数和路径的使用区别

• 是否是表示唯一资源所需的信息
• 是否可以省略