API:エチケット

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Etiquette and the translation is 34% complete.

Other languages:
English • ‎français • ‎italiano • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎日本語

This page contains the best practices that should be followed when using the API.

挙動

リクエストの上限

There is no hard and fast limit on read requests, but be considerate and try not to take a site down. Most system administrators reserve the right to unceremoniously block you if you do endanger the stability of their site.

Making your requests in series rather than in parallel, by waiting for one request to finish before sending a new request, should result in a safe request rate. It is also recommended that you ask for multiple items in one request by:

  • Using the pipe character (|) whenever possible e.g titles=PageA|PageB|PageC, instead of making a new request for each title.
  • Using a generator instead of making a request for each result from another request.

Use GZip compression when making API calls by setting Accept-Encoding: gzip to reduce bandwidth usage.

版の構文解析

revid パラメーターで版番号を指定して結果を取得するクエリを実行することもできますが、これはサーバーにとって負荷が高い処理です。 特定の版を取得するには、oldid パラメーターを使用します。例:

maxlag パラメーター

タスクが対話的ではない場合 (つまり、利用者が処理結果を待機しない場合) は、maxlag パラメーターを使用すべきです。 The value of the maxlag parameter should be an integer number of seconds. For example:

これにより、サーバーの負荷が高い場合に、タスクの実行を防止できます。 Higher values mean more aggressive behavior, lower values are nicer.

See Manual:maxlag パラメーター for more details.

User-Agent ヘッダー

It is best practice to set a descriptive User Agent header. To do so, use User-Agent: clientname/version (contact information e.g username, email) framework/version.... For example in PHP:

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');

人気があるウェブ ブラウザーの User-Agent をコピーしないでください。 これにより、問題が発生した場合に発生源を特定するのが容易になります。

If you are calling the API from browser-based JavaScript, you may not be able to influence the User-Agent header, depending on the browser. To work around this, use the Api-User-Agent header.

詳細は m:ユーザーエージェントのポリシー を参照してください。

Data formats

All new API users should use JSON . See API:データ形式 for more details.

Performance

If you are getting results more slowly than you would like, read the Performance guidelines to help you think about performance generally.

If reading via the API rather than directly reading from databases is impeding your client's performance, consider whether to put it into Wikimedia's Toolforge.

See also