NoSQL 与搜索 / 系统课时
REST API 请求规范
REST API 请求规范
本课把一条 Elasticsearch 请求拆成 HTTP 方法、资源路径、查询参数、请求头和 JSON 请求体,并通过写入文档的完整示例验证响应。掌握这些规则后,你可以在 Dev Tools 或程序客户端中准确定位请求错误。
学习目标
- 识别 Elasticsearch REST API 的组成部分与常用 HTTP 方法
- 正确编写资源路径、查询参数和 JSON 请求体
- 根据状态码和响应字段判断成功、冲突或参数错误
请求由哪些部分组成
一条典型请求可以写成 METHOD /资源路径?查询参数,需要提交数据时再附带 JSON 请求体。通过外部 HTTP 客户端调用时,还要设置认证信息与 Content-Type: application/json;Kibana Console 会复用当前登录身份并简化这些细节。
常用方法的含义由具体端点决定:GET 通常读取或查询资源,POST 常用于提交操作或让服务器生成文档 ID,PUT 常用于对明确路径或明确 ID 执行创建、替换或更新,DELETE 用于删除资源。不能只根据方法猜测行为,仍应以对应 API 文档为准。
路径、参数与请求体
资源路径从集群根路径开始,例如 /索引名/_doc/文档ID。查询参数放在 ? 后,多个参数用 & 连接,参数名通常使用下划线风格,如 filter_path。
请求体使用 UTF-8 JSON。字段名和字符串必须使用双引号,不能保留尾随逗号。Bulk 和 Multi Search 等批量接口使用逐行结构时,还必须按接口要求使用 NDJSON,不能把普通 JSON 数组直接当作批量请求体。
完整请求示例
下面的请求向 lesson-rest-api-demo 索引写入 ID 为 1 的商品文档。refresh=true 让新文档在请求结束后即可被搜索,适合教学验证,但高频写入场景不应对每次请求都强制刷新。filter_path 只保留本课关注的响应字段。
PUT /lesson-rest-api-demo/_doc/1?refresh=true&filter_path=_index,_id,_version,result
{
"name": "机械键盘",
"price": 399,
"inStock": true
}首次执行的预期结果:
HTTP 201{
"_index": "lesson-rest-api-demo",
"_id": "1",
"_version": 1,
"result": "created"
}再次执行相同请求时,文档 ID 不变,状态码通常变为 HTTP 200,result 变为 updated,_version 增加。这说明 PUT 到明确文档 ID 的请求可以重复覆盖该文档,而不是每次生成新 ID。
读取响应与错误
成功响应通常包含业务结果和资源元信息。写文档时常见字段有 _index、_id、_version 和 result;搜索响应则更关注 took、hits.total 与 hits.hits。应先看 HTTP 状态码,再看响应体,不要只凭某个字段判断成功。
常见状态码包括:200 表示请求成功,201 表示资源创建成功,400 表示请求格式或参数错误,401 表示未认证,403 表示权限不足,404 表示资源不存在,409 表示版本或创建冲突,429 表示集群暂时过载。
错误响应通常保留可定位的类型、原因和状态码:
{
"error": {
"type": "<ERROR_TYPE>",
"reason": "<ERROR_REASON>",
"root_cause": [
{
"type": "<ERROR_TYPE>",
"reason": "<ERROR_REASON>"
}
]
},
"status": 400
}调试时先核对方法与路径,再检查 JSON 是否闭合、字段类型是否正确,最后确认索引权限和集群负载。遇到 429 不应立即无间隔重试,应使用逐步延长等待时间的退避策略。
关键边界
Elasticsearch 的部分查询 API 支持带请求体的 GET,但某些 HTTP 库、代理或网关会忽略或拒绝 GET 请求体。遇到这类兼容问题时,可按该 API 的支持情况改用 POST,避免请求体在链路中丢失。
pretty=true 便于人工阅读,但会增加响应体积,生产程序不应默认开启。需要减少返回字段时优先使用 filter_path,需要追踪请求来源时可以由客户端设置稳定的请求标识,而不是把敏感信息放进 URL。
本课总结
- REST 请求应同时核对方法、资源路径、查询参数、请求头和 JSON 请求体
- 判断结果时先看 HTTP 状态码,再读取与当前 API 对应的响应字段
- GET 请求体、强制刷新和格式化输出都有使用边界,不能直接照搬到生产流量
下一课预告
下一课将基于这些请求规范练习索引、文档和查询操作,把接口格式转化为可重复执行的基础操作流程。