端点用于发起 HTTPS 请求,而 GET、POST、PUT、PATCH 和 DELETE 方法决定了如何与资源进行交互。
标题:使用句子大小写(首字母大写)的端点标题。标题末尾不使用标点符号。简单的情况通常采用以下形式之一:
操作/返回单个项目的端点:动词 + 不定冠词 + 单数资源名称。
- 示例:Get a list item
操作/返回项目集合的端点:动词 + 复数资源名称。
- 示例:Get list items
描述:描述端点的作用或应该如何使用。在描述末尾使用标点符号。
计划可用性:列出使用该端点所需的计划,例如 Free、Pro、Business 或 Enterprise。
方法:包括方法的类型,例如 GET、POST、PUT、PATCH 或 DELETE。
端点:列出端点,并应样式化为代码片段。
当某个端点将在指定的时间范围内被弃用但仍可用时,在端点描述中添加关于即将弃用的说明("<name of endpoint> will be deprecated on <full month name, date, year>. Use the <alternative endpoint> instead")。有关更多信息,请参阅 已弃用 API。
所需权限:使用该端点所需的、用户级别的其他权限。
在撰写标题和描述时,请牢记我们的声音和语气。保持简明扼要,并记住我们的用户来自各种不同的技术水平。此外,尽可能使用主动语态,以避免听起来像机器人,并使信息更容易理解。
以下是一些供参考的端点标题和描述示例:
- Get domain:获取单个域。
- List workers:获取已上传 Worker 的列表。
- List pools:列出已配置的池。
- Create waiting room:创建一个新的等候室。
- Update health check:更新已配置的健康检查。
标题:Get user audit logs
描述:获取用户账户的审计日志列表。
计划可用性:Free, Pro, Business, Enterprise
方法:GET
端点:user/audit_logs