主要用来规范自己写的 API，也是为了让 LLM 更好理解我的 API。

1. Domain

• 尽量单独使用一个域名，例如 api.example.com 。

2. Path

• 统一使用小写字母。
• 不用包含 /api 前缀。
• 不要包含扩展名。
• / 不要出现在末尾。 对于 Restful API，/ 用来划分资源层级，末尾的 / 会导致混淆。
• 使用带版本的路径 /v1 。
• 使用复数形式，例如 /v1/users 。
• 使用 - 代替 _ ，提高可读性，使用 /v1/mail-tasks 而不是 /v1/mail_tasks 。

3. Query

• 字段用小写的蛇形命名法，例如 ?first_name=abc 。
• query 的总长度应该在 2000 个字符以内。
• POST 方法不得使用 query 参数。
• 数组参数使用逗号分隔，例如 ?ids=1,2,3 。

4. Method

有很多国内团队，因为各种原因仅使用 GET 和 POST 方法，甚至只使用 POST 方法。在此仅按照语义来说明各个方法的用途。

• GET：获取资源，幂等，需要注意的是，GET 方法不应该修改资源，主要注意缓存问题。
• POST：创建资源，非幂等。
• PUT：更新资源，提供完整属性，幂等。
• PATCH：更新资源，提供局部属性，不幂等。
• DELETE：删除资源，幂等。
• HEAD：获取资源的元数据，幂等。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的，幂等。

5. Response

• 使用 JSON 格式。
• 使用 HTTP 状态码来表示请求状态。
• 使用 code 来表示业务状态码。
• 使用 message 来表示业务状态信息。
• 使用 data 来表示业务数据。
  • total 表示数据总数。
  • page 表示当前页码。
  • page_size 表示每页数据量。
  • list 表示数据列表。

6. Endpoint

• 使用名词而不是动词，例如 /v1/send-mail-tasks 或者 /v1/mails 而不是 /v1/send-mails

• 资源中不要包含动词，举个反例 POST /accounts/1/transfer/500/to/2 。

应该用名词来表示资源，动词应该用 HTTP 方法来表示。

1
2
3
4
5

POST /accounts/1/transfers
{
  "to_account_id": 2,
  "amount": 500
}

7. 参考

• https://github.com/OAI/OpenAPI-Specification