API:Etiquette/ja

このページでは、APIを使用する上で従うべきベストプラクティスについて説明します.

挙動


リクエストの上限
リクエストには制限はありませんが、サイトがダウンしないよう配慮しましょう. システム管理者は、あなたがサイトを不安定にすると、あなたをブロックすることがあります.

同時に複数個のリクエストを送るのではなく、1つづつ、前のリクエストが完了してから次のリクエストを送りましょう. また、複数のアイテムを1つのリクエストで問い合わせることが推奨されます.


 * 各タイトルごとにリクエストを発行するのではなく、利用可能な場合は常にパイプ文字（ ）を利用してください. 例:.
 * 他のリクエストの結果ごとに新しいリクエストを発行するのではなく、代わりにを使用してください.


 * 利用バンド幅を減らすために、 を設定して、GZip圧縮を有効にしてください.

Requests which make edits, modify state or otherwise are not read-only requests, are subject to rate limiting. The exact rate limit being applied might depend on the type of action, your user rights and the configuration of the website you are making the request to. 自分にかかっている制限は、action=query&meta=userinfo&uiprop=ratelimitsAPI エンドポイントにアクセスすることで見ることができます.

When you hit the request rate limit you will receive a with the error code. When you encounter this error, you may retry that request, however you should increase the time between subsequent requests. A common strategy for this is Exponential backoff.



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



maxlag パラメーター
タスクが対話的ではない場合 (つまり、利用者が処理結果を待機しない場合) は、 パラメーターを使用すべきです. パラメータの値は秒数を整数で指定する必要があります. 例:

これにより、サーバーの負荷が高い場合に、タスクの実行を防止できます. 数値が高い程アグレッシブで、低い方が良いです.

詳細は を参照してください.



User-Agent ヘッダー
叙事的なUser-Agentヘッダーの設定が最善です. そのためには、 を使用します. PHP の例:

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

If you are calling the API from browser-based JavaScript, you may not be able to influence the  header, depending on the browser. 回避するには、 ヘッダーを使用してください.

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



データフォーマット
すべての新規API利用者は. 詳細は を参照してください.

パフォーマンス
Downloading data in bulk is not always extremely efficient using the Action API. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.

Other notes
If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.

Also note that a request cannot be served from cache unless the URL is exactly the same. If you make a request for, and cache the result, then a request for   will not go through the cache — even though MediaWiki returns the same data!

You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.



関連項目

 * - クイックスタートガイド.