Discovery | WP REST API v2 Documentation の翻訳です。
Discovery 発見／探索
未知のサイトにアクセスする際、そのサイトでは何が可能でどのように設定されているのかを知る必要があります。何を知りたいのかによりますが、幾つかのステップで探索することができます。
API を見てみよう
最初のステップは、対象のサイトで API が有効化されているかどうかを確かめること。典型的には、ユーザーが入力した URL を利用することになるので、対象となるサイトはなんでもいいのです（注: この一文、意味不明。）。Discovery step を通じて、API が利用可能かどうかをたしかめて、どうやってアクセスするべきなのかを知りましょう。
LINK ヘッダー
URL に対して HEAD リクエストを送信するのが好ましいでしょう。REST API はフロントエンドのページに自動的に以下のような LINK ヘッダーを追記します。
Link: <http://example.com/wp-json/>; rel="https://api.w.org/"
WP REST API が追加したHEADER 情報。
この URL は API の root route （ルーティングの根っこ）となる / を指し示しており、これを次の探索ステップで使っていきます。
Pretty Permalinks が有効化されていないサイトでは、 /wp-json/ は WordPress によって自動的には扱われません。つまり、WordPress のデフォルトのパーマリンクが代わりに使われます。こんな感じになります。
Link: <http://example.com/?rest_route=/>; rel="https://api.w.org/"
パーマリンクをデフォルトに戻してみると、たしかに rest_route という GET パラメータがセットされる
クライアントを作るときには、このバリエーションがあることを念頭に置き、どちらのルート(route)であっても動くようにしないとです。
この autodiscovery は WordPress が動いているすべての URL に対して適用されているので、ユーザーの入力を事前に編集する必要はありません。HEAD リクエストなので盲目的にいろんなサーバにリクエストを送っても副作用を心配する必要はありません。
<link> 要素
HTML パーサーを備えたクライアントであれば、あるいはブラウザであれば、LINK ヘッダーに対応するのは html の <head> に含まれる <link> 要素となります。
ブラウザで動いている Javascript であれば DOM を通じて取得できます。
// jQuery で
var $link = jQuery( 'link[rel="https://api.w.org/"]' );
var api_root = $link.attr( 'href' );
// ネイティブの javascript で
var links = document.getElementsByTagName('link');
var link = Array.prototype.filter.apply( links, function ( item ) {
return ( item.rel === "https://api.w.org/" );
} );
var api_root = link[0].href;
ブラウザ内のクライアント、あるいは HTTP ヘッダーにアクセス出来ないクライアントではこの方法のほうが API 探索が容易と思われます。Atom / RSS フィードの発見方法に似てますよね。なので、既存のコードを利用したらいいと思います。
RSD (Really Simple Discovery)
XML-RPC discovery をサポートしているクライアントであれば、RSD method のほうがいいかもしれません。
（すいません、ちょっと長いし使いそうにないので中略）
認証の探索
API を通じた認証方法を見つけることもできます。API のルート(rootの方)のレスポンスは API のディスクリプションのオブジェクトであり、 authentication キーを含んでいます。
{
"name": "Example WordPress Site",
"description": "YOLO",
"routes": { ... },
"authentication": {
"oauth1": {
"request": "http://example.com/oauth/request",
"authorize": "http://example.com/oauth/authorize",
"access": "http://example.com/oauth/access",
"version": "0.1"
}
}
}
この authentication の値は、認証オプションの認証メソッド ID の map （連想配列）になっています。
WPサイトの任意のURLにアクセスした時にLINK ヘッダーを確認した時のURLにもう一度GETでリクエストすると authentication を含む諸々の情報がもらえる
The options available here are specific to the authentication method itself. （意味がわからなかった）くわしくは、authentication documentation のページ（か、本ブログでの翻訳記事）を見てください。
Extension を見つける
API があることを発見したら、次は API が何をサポートしているのかを見てみましょう。API のインデックスが開示しているのは API がサポートしているエクステンションの namespace です。
普通の WordPress（ver.4.4）のサイトですと、API のインフラ部分のみが利用可能で API の全エンドポイントは利用できません。oEmbedのエンドポイントは含まれます。
全 API が利用できるサイト（REST API プラグインが有効化されてるとか）だと、wp/v2 という項目が namespaces に含まれます。
これら、コアエンドポイントを利用する前に、API がサポートされているかを wp/v2 をチェックすることで確認すべきです。WordPress 4.4 は API のインフラ部分は有効化しますが、 wp/v2 配下のコアエンドポイント群は含みません。
同じメカニズムは、REST API をサポートしているプラグインを検知するのにも利用できます。たとえば以下のようなルート(routeの方)を登録しているプラグインがあったとしましょう。
<?php register_rest_route( 'testplugin/v1', '/testroute', array( /* ... */ ) );
そうすると、 testplugin/v1 という namespace がインデックスに追加されます。
オレオレエンドポイントを追加。
というわけで翻訳終了。
ちなみに、最後のエンドポイントの追加、上記の一行だけではダメで、以下のようにして ‘rest_api_init’ というアクションフックに対して関数をフックし、その中で register_rest_route() してやらないといけないです。
add_action( 'rest_api_init', function(){
register_rest_route(
'nskw-plugin/v0',
'/hello-nskw',
array()
);
} );
コメント