反馈

当 API 出现错误、无法满足您的需求、与这些文档不一致，或返回的错误没有告诉您该如何修改时，请发送 POST /v1/feedback。它既是为人设计的，也是为承担了此 API 大部分工作的编码助手设计的，这样遇到障碍的助手可以在同一次会话中直接报告，而不是绕过去。

curl https://api.maple.inc/v1/feedback \
  -H "Authorization: Bearer $MAPLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "unclear_error",
    "summary": "Waitlist join answers 400 without naming the field",
    "attempted": "Add a party of four to the waitlist",
    "expected": "The error names the field that failed",
    "endpoint": "POST /v1/waitlist_entries",
    "request_ids": ["req_3f2b7c1e-9a4d-4e8b-b1c2-5d6e7f8a9b0c"]
  }'

字段	是否必填	填写内容
kind	是	bug、missing_capability、docs_wrong、unclear_error 或 other
summary	是	一行文字，最多 200 个字符
attempted	否	您当时想做什么，描述目标而不是某次调用；如果反馈与具体任务无关，可以省略
expected	否	您期望 API 做什么
observed	否	它实际做了什么
endpoint	否	方法和路径，例如 POST /v1/waitlist_entries
request_ids	否	相关请求的 ID，最多十个，通常是它们的 x-request-id 值

引用您的请求

每个响应都带有 x-request-id 响应头。请把相关请求的 ID 放进 request_ids，因为它们能让我们看到您实际发送的请求的操作、状态和错误码。您发送反馈时，我们会把这些详情复制到反馈上，所以即使请求历史在七天后过期，这些信息仍然可读。如果某个 ID 无法与您应用在同一环境、最近七天内的请求匹配（例如来自其他系统的 ID），则会按您发送的原样保留；报告绝不会因为某个 ID 而被拒绝。

不会破坏的契约

编码助手可能从只编写一次、然后运行多年的代码中发送反馈，因此我们绝不会对 POST /v1/feedback 做出破坏性变更。我们可能会添加可选字段和新的 kind 值，响应也可能新增字段，所以请忽略您不认识的字段。我们不会删除或重命名字段、更改字段含义、将可选字段改为必填、添加必填字段、移除某个 kind，也不会收紧长度限制。今天能用的请求会一直有效。

接下来会怎样

API 会保存该报告，并返回 200，其中包含一个 status 为 received 的 feedback 对象。Maple 每周都会阅读反馈并决定要修改什么；发送反馈本身不会改变任何东西，API 也不会回复。请不要在文本中包含机密信息、API 密钥和顾客信息。

任何凭据都可以在任一环境中发送反馈，无需任何权限范围。每个应用在每个环境中每小时最多可发送 20 份报告；超出后 API 会返回 429，并带有 Retry-After 响应头。