REST APIの使用 - ディスカバリー（Discovery） - 《WordPress開発者リソース》日本語

APIの発見
認証発見
リソース発見

APIの発見

サイトに接続する最初のステップは、そのサイトにAPIが有効になっているかどうかを確認することです。通常、ユーザー入力からのURLを扱うことになるため、アクセスしているサイトは何でもあり得ます。発見ステップでは、APIが利用可能であることを確認し、どのようにアクセスするかを示します。

リンクヘッダー

発見を処理するための推奨方法は、提供されたアドレスにHEADリクエストを送信することです。REST APIは、次のようなリンクヘッダーをすべてのフロントエンドページに自動的に追加します:

Link: <http://example.com/wp-json/>; rel="https://api.w.org/"

このURLは、APIのルートルート（/）を指し、さらなる発見ステップに使用されます。

「美しいパーマリンク」が有効でないサイトでは、/wp-json/はWordPressによって自動的に処理されません。これは、通常の/デフォルトのWordPressパーマリンクが代わりに使用されることを意味します。これらのヘッダーは次のようになります:

Link: <http://example.com/?rest_route=/>; rel="https://api.w.org/"

クライアントはこのバリエーションを考慮し、両方のルートがシームレスに処理できることを確認する必要があります。

この自動発見は、WordPressインストールによって提供される任意のURLに適用できるため、ユーザー入力に対する前処理を追加する必要はありません。これはHEADリクエストであるため、サーバーに盲目的に送信しても副作用を引き起こす心配はありません。

要素

HTMLパーサーを持つクライアントやブラウザで実行されるクライアントの場合、リンクヘッダーの同等物は、<head>のフロントエンドページに<link>要素を通じて含まれています:

<link rel='https://api.w.org/' href='http://example.com/wp-json/' />

ブラウザ内のJavaScriptは、DOMを介してこれにアクセスできます:

// jQuery method
var $link = jQuery( 'link[rel="https://api.w.org/"]' );
var api_root = $link.attr( 'href' );
// Native method
var links = document.getElementsByTagName( 'link' );
var link = Array.prototype.filter.call( links, function ( item ) {
   return ( item.rel === 'https://api.w.org/' );
} );
var api_root = link[0].href;

ブラウザ内のクライアントやHTTPヘッダーにアクセスできないクライアントにとって、これはAPIを発見するためのより使いやすい方法かもしれません。これはAtom/RSSフィードの発見に似ているため、その目的のための既存のコードも自動的に適応される可能性があります。

RSD（本当にシンプルな発見）

XML-RPC発見をサポートするクライアントの場合、RSDメソッドがより適用可能かもしれません。これは、XML-RPCに通常使用されるXMLベースの発見フォーマットです。RSDには2つのステップがあります。最初のステップは、<link>要素として提供されるRSDエンドポイントを見つけることです:

<link rel="EditURI" type="application/rsd+xml" title="RSD" href="http://example.com/xmlrpc.php?rsd" />

2番目のステップは、RSDドキュメントを取得し、利用可能なエンドポイントを解析することです。これは、次のようなドキュメントにXMLパーサーを使用することを含みます:

<?xml version="1.0" encoding="utf-8"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
  <service>
   <engineName>WordPress</engineName>
   <engineLink>https://wordpress.org/</engineLink>
   <homePageLink>http://example.com/</homePageLink>
   <apis>
   <api name="WordPress" blogID="1" preferred="true" apiLink="http://example.com/xmlrpc.php" />
   <!-- ... -->
   <api name="WP-API" blogID="1" preferred="false" apiLink="http://example.com/wp-json/" />
   </apis>
  </service>
</rsd>

REST APIには常にname属性があり、その値はWP-APIに等しいです。

RSDは、いくつかの理由から自動発見の中で最も好まれない方法です。RSDベースの発見の最初のステップは、RSDドキュメント自体を見つけるためにHTMLを解析することを含み、これは<link>要素の自動発見に相当します。その後、RSDドキュメントを解析するための別のステップが必要で、完全なXMLパーサーが必要です。

可能な限り、複雑さのためにRSDベースの発見を避けることをお勧めしますが、既存のXML-RPCクライアントは、すでにRSDパーサーが有効になっている場合、この方法を使用することを好むかもしれません。REST APIをコードベースへのプログレッシブな拡張として使用したいXML-RPCクライアントにとって、異なる発見形式をサポートする必要がなくなります。

認証発見

発見は、APIを介して利用可能な認証方法にも利用可能です。APIルートの応答は、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"
   }
   }
}

 <a name="extension-discovery"></a>
## 拡張発見
APIを発見したら、次のステップはAPIがサポートしているものを確認することです。APIのインデックスは、サポートされているAPIの拡張を含む`````namespaces`````アイテムを公開します。  
WordPressサイトがバージョン4.4から4.6を使用している場合、基本APIインフラストラクチャのみが利用可能で、エンドポイントを含む完全なAPIは利用できません。これにはoEmbedエンドポイントも含まれます:  
``````bash
{
   "name": "Example WordPress Site",
   "namespaces": [
   "oembed/1.0/"
   ]
}
`

完全なAPIが利用可能なサイト（つまり、WordPress 4.7以上またはREST APIプラグインがインストールされている場合）では、wp/v2アイテムがnamespacesにも存在します:

{
   "name": "Example WordPress Site",
   "namespaces": [
   "wp/v2",
   "oembed/1.0/"
   ]
}

コアエンドポイントを使用しようとする前に、wp/v2サポートを確認してAPIがサポートされていることを確認する必要があります。WordPress 4.4はすべてのサイトにAPIインフラストラクチャを有効にしましたが、wp/v2の下にコアエンドポイントは含まれていませんでした。コアエンドポイントはWordPress 4.7で追加されました。

このメカニズムは、REST APIをサポートする任意のプラグインのサポートを検出するためにも使用できます。たとえば、次のルートを登録するプラグインを考えてみてください:

<?php
register_rest_route( 'testplugin/v1', '/testroute', array( /* ... */ ) );

これにより、インデックスにtestplugin/v1名前空間が追加されます:

{
   "name": "Example WordPress Site",
   "namespaces": [
   "wp/v2",
   "oembed/1.0/",
   "testplugin/v1"
   ]
}

リソース発見

WordPress 5.5以降、REST APIは現在のドキュメントのREST APIルートの同等物を特定するための発見メカニズムも提供します。リンクは、relがalternateで、typeがapplication/jsonのREST API URLを指すように追加されます。このリンクは、Linkヘッダーと<link>要素の両方として追加されます。

たとえば、このページの<head>セクションには、次の<link>が表示されます。

<link rel="alternate" type="application/json" href="https://developer.wordpress.org/wp-json/wp/v2/rest-api-handbook/23085">

リンクは、投稿、ページ、その他のカスタム投稿タイプ、用語、著者ページに追加されます。投稿アーカイブや検索結果には現在リンクは出力されていません。