重要なコンセプト
TOPICS
翻訳元記事はこちらです。
このページでは、REST APIに関する概念と反する箇所がいくつかあるかもしれません。
- ルート & エンドポイント
- リクエスト
- レスポンス
- スキーマ
- コントローラー
これらの概念は、WordPress REST APIを使うにあたって重要な役割を持っています。それぞれをこのハンドブックで掘り下げていきます。
ルート & エンドポイント
WordPress REST APIのルートURIは、異なるHTTPのメソッドにマッピングされています。それぞれのHTTPメソッドは、エンドポイントというルートにマッピングされています。
たとえば、http://oursite.com/wp-json/というURIにGETメソッドでリクエストを投げたとき、どのルートが使えるか、どのエンドポイントがそれぞれのルートで使えるかをJSON形式で返します。/wp-json/に、GETメソッドでリクエストを投げると、エンドポイントによって処理されます。wp-json/wp/v2/postsというルートは、GETメソッドだと投稿一覧を返し、POSTメソッドだと新しい投稿を作るための認証をします。
続いてのセクションでは、どのようにルートとエンドポイントを登録するかを学びます。
もしあなたが、整っていないパーマリンクを使用している場合、REST APIにクエリストリングを渡すべきです。http://oursite.com/wp-json/このURLの場合は、このようになります。http://oursite.com/?rest_route=/
もしhttp://oursite.com/wp-json/にアクセスしようとして、404エラーが返ってきた場合は、整ったパーマリンクを使うか、rest_routeパラメーターを追加してください。
リクエスト
REST APIのリクエストは、WordPressでは、WP_REST_Requestクラスのインスタンスによって表示されます。そのクラスは、現在のリクエストの情報を保存および取得するのに使われます。WP_REST_Requestオブジェクトは、HTTPリクエストがAPIのルートに登録されたときに、自動的に生成されます。このオブジェクトに指定されたデータは、APIからどういったレスポンスを受け取るか決定します。（オブジェクトは、URIルートに由来する、または、リクエストの一部として送信されたJSONのデータのことです。）
リクエストは、通常はHTTPを介してリモートから提供されます。しかし、WordPressのプラグインやテーマのコードから提供されることもあります。このことについては、ハンドブックの他の箇所で詳しく解説します。
レスポンス
レスポンスは、APIから受け取るデータのことです。WP_REST_Responseクラスは、エンドポイントによって返されるデータに関わる方法を提供します。レスポンスは、リクエストされたデータを返し、エラーがある場合にはエラーを返します。
スキーマ
それぞれのエンドポイントは、特定の構造を必要とします。そして、決められた構造でデータを返します。データ構造は、APIスキーマによって決められています。
スキーマは、APIが返せるプロパティのリストを提供し、APIが受け取れるパラメーターを提供します。きちんと定義されたスキーマは、セキュリティ層を提供します。APIによるリクエストのバリデーション、サニタイズを可能にします。スキーマセクションでは、このテーマについて解説します。
コントローラークラス
コントローラークラスは、REST APIのレスポンスのサイクルを統一します。コントローラークラスによって、ルートとエンドポイントを管理して、リクエストを扱い、スキーマを活用し、APIのレスポンスを作成することができます。
１つのクラスは、与えられたルートのすべてのロジックを含んでおり、与えられたルートは、WordPressサイトの特定のデータを表します。（カスタム投稿タイプやタクソノミーなど）