# HTTP API 速查表

Source: https://codewiki.com/zh/cheatsheets/http/

## 资源与方法

- `GET /orders/ord-42` — 读取资源表示且不改变资源状态；安全且幂等
- `HEAD /orders/ord-42` — 只读取响应元数据，不返回响应内容；安全且幂等
- `POST /orders` — 让集合处理一个表示；常用于创建成员，本身不保证幂等
- `PUT /orders/ord-42` — 在已知目标创建或替换表示；幂等
- `PATCH /orders/ord-42` — 按补丁媒体类型定义的规则执行部分修改；本身不保证幂等
- `DELETE /orders/ord-42` — 请求删除目标；预期效果是幂等的
- `OPTIONS /orders` — 查询目标支持的通信选项；安全且幂等

## Node 客户端

- `const response = await fetch('https://api.example.com/orders')` — 用 Node 24 的全局 `fetch` 发送 GET 请求
- `await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(order) })` — 发送 JSON，并明确指定请求媒体类型
- `response.ok` — 检查状态码是否在 200–299 范围内
- `response.headers.get('content-type')` — 以不区分大小写的方式读取响应头
- `const data = await response.json()` — 一次性消费响应内容并解析为 JSON
- `await fetch(url, { signal: AbortSignal.timeout(5000) })` — 五秒后中止请求

## 成功响应

- `200 OK` — 返回成功的表示或操作结果
- `201 Created` — 说明请求已经创建资源
- `Location: /orders/ord-42` — 在 `201` 响应中标识新建资源
- `202 Accepted` — 说明处理已接受但尚未完成；还要定义客户端如何观察完成状态
- `204 No Content` — 说明操作成功且没有响应内容

## 客户端错误

- `400 Bad Request` — 拒绝语法、消息构造或请求输入有误的请求
- `401 Unauthorized` — 拒绝缺少认证或凭据无效的请求，并返回质询
- `403 Forbidden` — 拒绝调用方无权执行但服务端已经理解的请求
- `404 Not Found` — 说明资源不存在，或隐藏调用方不应发现的资源
- `409 Conflict` — 说明请求与资源当前状态冲突
- `412 Precondition Failed` — 拒绝条件请求头求值为假的请求
- `422 Unprocessable Content` — 拒绝格式正确但指令无法处理的内容

## 服务端压力

- `429 Too Many Requests` — 说明该客户端已超过速率限制
- `500 Internal Server Error` — 说明服务端发生意外故障，不暴露内部细节
- `502 Bad Gateway` — 说明网关收到无效的上游响应
- `503 Service Unavailable` — 说明服务因过载或维护而暂时不可用
- `504 Gateway Timeout` — 说明网关未能及时收到上游响应
- `Retry-After: 120` — 在 `429` 或 `503` 后要求客户端等待 120 秒

## 表示格式

- `Content-Type: application/json` — 标明请求或响应内容的媒体类型
- `Accept: application/json` — 请求 JSON 响应表示
- `Content-Type: application/problem+json` — 标明 RFC 9457 问题详情文档
- `406 Not Acceptable` — 说明可用响应表示都不满足 `Accept`
- `415 Unsupported Media Type` — 拒绝格式或编码不受支持的请求内容
- `Content-Encoding: gzip` — 声明表示数据采用 gzip 内容编码

## 缓存

- `Cache-Control: no-store` — 要求缓存不要存储此响应
- `Cache-Control: private, max-age=60` — 允许私有缓存在响应新鲜期间复用它
- `Cache-Control: public, max-age=300` — 在契约允许时，让共享缓存复用响应
- `ETag: "order-7"` — 为选定表示附加不透明验证器
- `If-None-Match: "order-7"` — 用实体标签重新验证缓存的表示
- `304 Not Modified` — 复用缓存的表示；该响应不携带消息内容
- `Vary: Accept-Encoding` — 为接受不同编码的请求保留独立缓存条目

## 并发与重试

- `If-Match: "order-7"` — 仅在当前强实体标签匹配时执行修改
- `428 Precondition Required` — 要求客户端发送条件请求
- `idempotent: GET, HEAD, OPTIONS, PUT, DELETE` — 重复相同请求的预期效果与发送一次相同
- `not inherently idempotent: POST, PATCH` — 仅当应用契约提供安全去重语义时重试
- `Idempotency-Key: 7b1d7a90` — 同一逻辑操作的每次重试都复用应用定义的同一键和请求体

## 分页

- `GET /orders?status=pending` — 用文档明确的查询参数过滤集合
- `GET /orders?limit=50` — 请求有界的页大小；服务端仍要强制执行上限
- `GET /orders?cursor=eyJpZCI6Im9yZC00MiJ9` — 用绑定到相同过滤条件与排序的不透明游标继续读取
- `ORDER BY created_at DESC, id DESC` — 用唯一决胜字段形成完整且确定的分页顺序
- `Link: </orders?cursor=next>; rel="next"` — 给出下一页目标，客户端无需自行构造

## 认证与 CORS

- `Authorization: Bearer ACCESS_TOKEN` — 通过 TLS 向资源服务器发送 Bearer 访问令牌
- `WWW-Authenticate: Bearer realm="orders"` — 质询缺少或使用无效 Bearer 凭据的请求
- `Origin: https://app.example.com` — 标明发起请求的浏览器源；它不能认证用户
- `Access-Control-Allow-Origin: https://app.example.com` — 允许该源的浏览器代码读取跨源响应
- `Access-Control-Allow-Methods: GET, POST` — 列出预检响应允许的方法
- `Access-Control-Allow-Headers: Authorization, Content-Type` — 列出预检允许的非简单请求头
- `Access-Control-Allow-Credentials: true` — 只与明确允许的源搭配，以准许浏览器携带凭据

## 契约演进

- `GET /api/v1/orders` — 通过路径选择主版本 API 契约
- `Accept: application/vnd.example.orders.v2+json` — 通过内容协商选择版本化表示
- `Vary: Accept` — 防止缓存混用由 `Accept` 选择的不同表示
- `Deprecation: @1798761600` — 用 RFC 9651 日期标明弃用时刻，但不改变当前行为
- `Sunset: Thu, 01 Jul 2027 00:00:00 GMT` — 标明资源预计何时停止响应

## 契约检查

- `import assert from 'node:assert/strict'` — 在 API 契约测试中使用 Node 严格断言
- `assert.equal(response.status, 201)` — 锁定操作的确切成功状态码
- `assert.equal(response.headers.get('location'), '/orders/ord-42')` — 锁定必需的响应头
- `assert.deepEqual(await response.json(), expectedBody)` — 锁定契约承诺的响应表示
- `assert.equal(await response.text(), '')` — 验证 `204` 响应没有内容
- `assert.equal(response.headers.get('etag'), expectedEtag)` — 锁定条件请求所需的验证器