GET-操作模式

GET - Action 是客户端的有界可写回退，只能构建简单的 URLs。它与最小访问权限分开，并且不能替代 POST JSON API。

路线格局#

GET /api/{version}/{resource}/{action}?param1=value&idempotency_key=stable-key

需要同伴#

每个可以更改状态的 GET-Action 端点都应该有一个匹配的 POST 端点，用于 L2 和更高版本的客户端。 POST 路径拥有更丰富的请求正文、结构化错误、身份验证流程和普通 API 行为。

所需的控制#

• 幂等性：每个可写的 GET-Action 都需要一个稳定的 idempotency_key。
• 同意：该行动在执行之前必须是公共安全的或明确经过人类批准的。
• 可审核性：存储规范化操作、调用者类、结果、时间戳、幂等性密钥和公共安全证据。
• 速率限制：在执行操作之前强制执行爬虫安全和防滥用限制。
• 机器人和爬行器：将操作排除在站点地图之外，并尽可能拒绝爬虫触发的执行。
• 实时 GET 后备：如果操作 URL 需要实时动态 HTTP GET，请为仅索引提取器提供无操作或审查 URL。
• 查询字符串中没有秘密：切勿将令牌、密码、API 密钥、患者 ID、私人消息或支付数据放置在 URL 中。

响应形状#

{
  "status": "accepted",
  "action_executed": false,
  "resource_id": "public-record-id",
  "machine_data": {},
  "human_readable_url": "https://example.org/review/action/",
  "next_actions": ["human_review_required"]
}

允许使用#

• 当客户端不可用 POST 时，简单的公共安全偏好、确认、审核请求或队列接收操作。
• 可以使用相同幂等键安全地重复的操作。
• 不会暴露 URL 中任何秘密、受监管、财务、医疗或私人标识符的操作。

禁止使用#

• 付款、帐户更改、破坏性行为、发布、不可逆转的写入、医疗行为或未经更强大的经过身份验证的 POST 路径和明确审查的受监管操作。
• 任何依赖于查询字符串秘密的端点。
• 任何可写操作通常应公开为 GET 端点的广泛声明。

相关记录#

• GET-操作安全详细的安全检查表和无秘密规则。
• 代理人同意范围具有行动能力的代理的人工批准规则。
• 高级代理支持POST-L2+ 客户的首要且有证据的行为。