API:礼仪
 | 本页是MediaWiki Action API帮助文档的一部分。 |
 | 本頁簡而言之：
|
本页面包含使用API时应遵循的最佳实践。
行为
请求限制
读取请求没有严格的速度限制，但请体谅他人，尽量不要导致网站瘫痪。 如果你威胁到站点的安全，多数管理员保留将你封禁的权力。
以串行方式而非并行方式发送请求，即等待一个请求完成后再发送下一个请求，这样可以确保请求速率保持在安全范围内。 如果你要操作多个项目，应该遵守以下条件：
- 只要能用管道符号（
|）就不要为每个标题都创建一个新请求，例如titles=PageA|PageB|PageC。 - 使用生成器而不是对另一个请求的每个结果发出请求。
- 进行API调用时使用GZip压缩减少带宽消耗。
涉及编辑、修改状态或其他非只读操作的请求均受速率限制。具体的速率限制可能取决于操作类型、您的用户权限以及您发出请求的网站配置。 可以通过访问action=query&meta=userinfo&uiprop=ratelimits API端点来确定适用于您的限制。
当您达到请求速率限制时，您将收到一个包含错误代码ratelimited的API 错误响应。遇到此错误时，您可以重试该请求，但应增加后续请求之间的时间间隔。一种常用的策略是指数退避算法。
解析修订版本
虽然可以使用revid参数查询特定修订版本的结果，但这对服务器来说是一项耗费资源的操作。
要检索特定版本，请使用oldid参数。例如：
最大延迟参数
如果您的任务是非交互式的，也就是说用户无需等待结果，那么您应该使用maxlag参数。
参数maxlag的值应该是一个整数，表示秒数。
例如：
这将防止在服务器负载较高时运行您的任务。 数值越高表示行为越具有攻击性，数值越低表示行为越友善。
要了解更多详情，请参见手册:Maxlag参数。
User-Agent标头
最佳做法是设置描述性用户代理标头。
为此，请使用User-Agent: 客户端名称/版本（联系信息，例如用户名、电子邮件）框架/版本……。
例如在PHP中：
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
不要简单地复制常见浏览器的用户代理。 这样可以确保，即使出现问题，也能很容易地追溯到问题的根源。
如果您是通过基于浏览器的JavaScript调用API，则根据浏览器的不同，您可能无法控制User-Agent标头。
要解决此问题，请使用Api-User-Agent标头。
数据格式
所有新的API用户应使用JSON。 有关更多详细信息，请参见API:数据格式。
快取
如果你请求获取的数据可以缓存一段时间，你应该采取措施对其进行缓存，这样就无需反复请求相同的数据。 有些客户端可能能够自行缓存数据，但对于其他客户端（特别是JavaScript客户端）来说，这是不可能的。
POST 請求
每当您从网络服务API读取数据时，如果可能，应尽量使用GET请求而不是POST请求，因为后者无法缓存，并且在多数据中心的配置（包括维基媒体网站）中，数据可能会被发送到更远的数据中心。
在极少数情况下，如果您确实需要使用POST方法进行读取请求，例如调用action=parse并传递一段很长的维基文本字符串，请考虑设置Promise-Non-Write-API-Action: true标头。
这有助于确保您的POST请求（如果适用）由距离最近的数据中心中的应用服务器进行处理。
对于GET请求，无需设置此标头；使用CentralAuth在wiki家族中进行跨Wiki请求时，也不应该设置此标头；请参阅T91820。
針對維基媒體的維基指南
除了上述最佳實踐之外，使用Action API存取Wikimedia的各個wiki時還應遵循以下準則。 参见维基媒体基金会治理维基站上的官方API使用指引。
User-Agent 政策
對Wikimedia的各個wiki的API請求必須包含一個有意義的 User-Agent 標頭。 要了解更多详情，请参见用户代理方针。
速率限制
除了基於使用者操作的速率限制之外，對Wikimedia wiki的API請求還受到API速率限制的約束。
性能
使用Action API批量下载数据并非总是非常高效。 在维基媒体的维基网站上，有更快获取批量数据的方法，详情请参阅m:Research:Data和wikitech:Portal:Data Services。
参见
- 维基媒体基金会治理维基上的官方API使用指南
- Wikitech上的维基媒体机器人政策
- API:Main page - 快速入门指南。
- Manual:Rate limits & Wikimedia APIs/Rate limits
程式碼監管
- 由MediaWiki Interfaces Team维护。
- 即时聊天（IRC）：#mediawiki-core 在线
- 问题追踪器：Phabricator MediaWiki-Action-API（报告问题）