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 只保留本课关注的响应字段。

http
PUT /lesson-rest-api-demo/_doc/1?refresh=true&filter_path=_index,_id,_version,result
{
  "name": "机械键盘",
  "price": 399,
  "inStock": true
}

首次执行的预期结果:

text
HTTP 201
json
{
  "_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 表示集群暂时过载。

错误响应通常保留可定位的类型、原因和状态码:

json
{
  "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 请求体、强制刷新和格式化输出都有使用边界,不能直接照搬到生产流量

下一课预告

下一课将基于这些请求规范练习索引、文档和查询操作,把接口格式转化为可重复执行的基础操作流程。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

REST API 请求规范

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通