API:REST API

From mediawiki.org
This page is a translated version of the page API:REST API and the translation is 97% complete.
Languages:

MediaWiki の REST API は、rest.php URL に HTTP リクエストを送り、MediaWiki とやりとりができます。 APIを使用するとアプリやスクリプトを構築し、Wikiページの検索と表示や、メディアファイルの取得、ページ履歴の探索ができます。

クイックスタート

# 地球を主題とする記事を英語版ウィキペディアで検索 $ curl "https://en.wikipedia.org/w/rest.php/v1/search/page?q=earth&limit=1"

試してみる

データ形式

REST APIエンドポイントが返すデータ形式はJSONまたはHTMLです。 エンドポイント単位の適合するコンテンツの種別はAPI 参考情報を参照してください。

メソッド

APIは標準の HTTPリクエストメソッドに対応します。

GET リソースを取得
HEAD GETリクエストに対して 反応データをつけない HTTPヘッダを返す
POST リソースの作成
PUT リソースの更新または作成

URL の構造

APIエンドポイントは一貫したURL構造を共有し、ウィキのベースURL、ウィキのスクリプトパスおよびAPIバージョンを含みます。 

# URL の構造
[プロジェクトの URL]/[スクリプトのパス]/rest.php/v[バージョン番号]/

# URLのサンプル：英語版ウィキペディアの沿革を取得
https://en.wikipedia.org/w/rest.php/v1/page/Main_Page/history

バージョン化

MediaWiki REST APIは開発者に長期的な安定性を提供するように設計され、APIパスのグローバルバージョン番号を使ってバージョンを管理します（例：/v1/）。 [1]の原則に従って、エンドポイントに下位互換性のない方法で応答プロパティの削除や必要なパラメータの追加などの変更があると、バージョンが1つ増えます。 メジャーなバージョン変更に際して、APIは下位互換性のある方法で応答プロパティやオプションのリクエストパラメータなどを追加することがあります。

/v1/ (最新) MediaWiki 1.35 で利用可能

許諾と認証

REST APIの設定は利用者の証明や認証にOAuth 拡張機能を採用します。 ただしAPIは認証方法に関係なくログイン利用者の存在に応答し、その利用者の権限に適したコンテンツを返します。

REST APIを使ってウィキメディアのプロジェクト群にアクセスするには

REST API を使ってウィキペディア、ウィクショナリーその他のウィキメディアの多言語のプロジェクト群にアクセスできます。 ウィキメディアのプロジェクト群のURL総覧は、メタウィキのサイトマトリクスを参照してください。

リクエストの上限

APIに対するリクエストには確定した上限値はないものの、特定のサイトの安定性を乱した利用者のクライアントと判断すると、ご利用のクライアントをブロックする場合があります。 安全なリクエスト件数の範囲にとどまるには、各リクエストが終了するのを待ってから新たなリクエストを送信します。

クライアントの識別

APIリクエストに対して、ウィキメディアのサイト群は必ずHTTP ユーザーエージェントを要求します。 これは、皆さんのアプリの特定と問題が発生したときに皆さんに連絡するシステム管理者に役立ちます。 ユーザエージェントのヘッダを持たないクライアントがリクエストする場合、通知なしにIPブロックされる場合があります。

ユーザー エージェントのヘッダーに書き込む情報は、ローカル ウィキの利用者ページや、関連ウィキでウィキ間リンク構文を使った利用者ページ、関連する外部ウェブサイトの URL、またはメールアドレスから選べます。 

# ユーザエージェントのヘッダに適した形式
<クライアント名>/<バージョン> (<連絡先情報>) <ライブラリ/フレームワーク名>/<バージョン>

ブラウザベースのJavaScriptからAPIを呼び出す場合、ブラウザによってはユーザエージェントのヘッダを変えることができない場合があります。 回避するには、Api-User-Agentヘッダーを使用してください。 詳細はメタウィキのユーザーエージェントの方針をご参照ください。

認証

個別の利用者の代わりに皆さんのアプリを認証するには、アプリの登録とOAuthトークン使用の許諾はOAuth 開発者ガイドを参照してください。

ライセンスと商標

ウィキメディアのコンテンツは、該当するライセンスで指定された規約の範囲で自由に再利用できます。 ライセンスはプロジェクトごとに異なり、個別のプロジェクトのライセンスとコンテンツ利用の情報を参照してください。 一例として英語版ウィキペディアの文章の再利用は クリエーティブコモンズ表示-継承 3.0 非移植の規約に従いますが、ウィキメディア・コモンズにあるメディアファイルはそれぞれの情報源ページに個別にライセンス条件を示してあります。 ライセンス要件と商標使用に関する詳細は、メタウィキの開発者ガイドラインを参照してください。

ウィキデータの制限事項

REST API はウィキメディアのプロジェクト群で利用可能ですが、 ウィキデータとの連係は完全ではありません。 この原稿の時点では、エンドポイントによっては想定外のエラーを返す可能性があります。 Instead, use the Wikidata REST API.

拡張機能のエンドポイント

REST API拡張機能を使うと、 MediaWiki 拡張機能の固有のAPI エンドポイントを可視化できます。 最初にREST API 拡張機能のインタフェース文書 を読んでから作業を始めてください。 REST API 拡張機能から得られるエンドポイントに関する解説文書は、 拡張機能の解説文書を参照してください。 REST API 拡張インタフェースは$wgEnableRestAPI 経由でMediaWiki 1.34 から、またMediaWiki 1.35 でも入手でき、今後は既定で展開する予定です。

APIの対比

この表: 閲覧 · トーク · 編集
API Availability URL base 例
MediaWiki 操作 API MediaWiki に同梱されています

ウィキメディアのプロジェクト群で有効になっています

/api.php https://ja.wikipedia.org/w/api.php?action=query&prop=info&titles=地球
MediaWiki REST API MediaWiki 1.35 以降に同梱されています

ウィキメディアのプロジェクト群で有効になっています

/rest.php https://ja.wikipedia.org/w/rest.php/v1/page/地球
ウィキメディア REST API MediaWiki に同梱されていません

ウィキメディアのプロジェクト群のみで利用できます

/api/rest https://ja.wikipedia.org/api/rest_v1/page/title/地球
For commercial-scale APIs for Wikimedia projects, see Wikimedia Enterprise

文書について

これらの解説文書はMediaWiki コアソースコードに従い、書き下ろしました。 訂正や加筆をお待ちしています。 MediaWiki REST API関連のチュートリアルやアプリの紹介は、REST API テンプレートを編集してリンクを記入してください。

関連項目


Retrieved from "https://www.mediawiki.org/w/index.php?title=API:REST_API/ja&oldid=6477396"