wp-rest-api

wp-rest-api スキルの概要

wp-rest-api は何のためのものか

wp-rest-api スキルは、WordPress の REST エンドポイント作業を、勘に頼らず進めやすくするためのものです。ルートの作成、コンテンツタイプの公開、パラメータ検証、レスポンス整形、認証や権限エラーの修正までカバーします。単なる汎用プロンプトではなく、実際のプラグイン、テーマ、mu-plugin の中で API Development を進めるための実践的な wp-rest-api ガイドが必要なときに、特に役立ちます。

どんな人に向いているか

register_rest_route()、WP_REST_Controller、register_rest_field、register_meta、show_in_rest、あるいは REST の schema / validation ロジックを追加・デバッグしているなら、この wp-rest-api スキルを使ってください。自分の endpoint 作業に対して、この repo が対応できるか、そして安全にどう進めるべきかを素早く判断したい開発者に、特に相性のよい選択肢です。

何が違うのか

このスキルは、導入を止めがちな WordPress 固有の制約に焦点を当てています。たとえば permission_callback、nonce や application password による auth、route の namespace 設計、context=edit、_fields、schema ベースの validation などです。wp-rest-api の主な価値は、実装に入る前に正しい REST パターンへ導いてくれることにあります。これにより、壊れた権限設定、クライアント側の regressions、無効な response shape を減らせます。

wp-rest-api スキルの使い方

インストールして対象範囲を確認する

npx skills add WordPress/agent-skills --skill wp-rest-api で wp-rest-api スキルをインストールします。編集に入る前に、正しい repo root にいることを確認し、どの plugin / theme が entrypoint なのかを特定してください。プロジェクトがサイト全体の codebase なら、endpoint を所有する単一の component に絞り込みます。

最小限の入力をそろえる

wp-rest-api install をうまく進めるには、次の情報を用意すると効果的です。target namespace と version、route path、想定する HTTP method、auth mode、WordPress の最低対応 version です。弱い依頼は「endpoint を追加して」です。より強い依頼は、たとえば「my-plugin/v1/orders を認証済み editor 向けに追加し、返すのは order ID、status、total のみ。page と per_page を validate し、クライアント性能のために ?_fields= もサポートする」といった形です。

先に読むべきファイル

まず SKILL.md を確認し、そのあと references/routes-and-endpoints.md、references/authentication.md、references/schema.md、references/responses-and-fields.md、references/discovery-and-params.md、references/custom-content-types.md を見てください。これらのファイルには、route、permission、schema、コンテンツ公開をどう組む想定なのかが書かれており、repo を闇雲に眺めるよりずっと実用的です。

実務的なワークフローに沿って進める

まず既存の REST 利用状況をこのスキルで整理し、そのうえで実装方針を決めます。custom route にするのか、controller class にするのか、既存 type を公開するのかを見極めてください。prompt は endpoint 名だけでなく、想定する resource の形を中心に組み立てます。たとえば、その response が public なのか edit-only なのか、core fields を再利用するのか、データの由来が post meta なのか CPT なのか、それとも計算ロジックなのかを含めます。そうすることで、モデルが実用的な wp-rest-api usage の結果を出しやすくなります。

wp-rest-api スキル FAQ

カスタム route 専用ですか？

いいえ。wp-rest-api スキルは、show_in_rest で CPT や taxonomy を公開したり、custom field や meta を追加したり、既存 endpoint の response 挙動を調整したりする用途にも向いています。一度きりの fetch 例だけなら、普通の prompt で足りることもありますが、route 設計や互換性チェックが必要なら、このスキルのほうが適しています。

wp-rest-api を使わないほうがいいのはどんなときですか？

WordPress の REST internals と関係ない作業なら、使う必要はありません。また、すでに安定している API を consume するだけの client app で作業している場合も、対象外です。server code を変更できず、documentation や request 例だけが欲しい場合も、あまり向いていません。

初心者でも使えますか？

はい。WordPress の PHP ファイルを編集できて、欲しい resource を明確に説明できるなら問題ありません。初心者がつまずきやすいのは auth と permission の指定不足で、見た目は動いているのに、ログアウト中のユーザー、editor、外部 client では失敗する route になってしまう点です。

汎用 prompt と比べるとどう違いますか？

汎用 prompt でも code は出せますが、wp-rest-api は WordPress 固有のガードレールが必要なときにより有効です。たとえば必須の permission_callback、schema validation、response shaping、route discovery などです。syntax だけでなく reliability を重視する install decision では、このスキルのほうが適しています。

wp-rest-api スキルを改善するには

ゴールだけでなく、resource の形を伝える

最も効果が大きい改善は、endpoint が何を返し、誰が呼べるべきかを具体的に指定することです。object type、fields、write access、特殊な filter を明示してください。例: 「published products を id、name、price、stock_status 付きで返し、stock_status だけは認証済み manager が更新できるようにする」。こうすると wp-rest-api スキルの精度が大きく上がります。

失敗の状況を最初に書く

デバッグなら、症状を具体的に入れてください。401 なのか 403 なのか 404 なのか、nonce の不足なのか、namespace の不一致なのか、schema エラーなのかを明記します。route が public なのか、cookie-authenticated なのか、application passwords を使うのかも書いてください。そうすると、モデルは auth failure と route registration / data-shape の問題を切り分けやすくなります。

prompt に repo の具体情報を入れる

repo にすでにある関連ファイル、controller class、post type を名前で挙げてください。コード側にすでに show_in_rest、rest_base、meta registration があるなら、その点も書きます。質の高い wp-rest-api guide の出力は、既存アーキテクチャに結びついた prompt から生まれることが多く、ゼロからの新規実装を求めるよりはるかに安定します。

validation から polish へ段階的に詰める

最初の出力のあとで、改善は一度に一つだけ頼むのが効果的です。たとえば、schema を厳密にする、permission check を強化する、_fields で response を絞る、non-pretty permalink 環境との route 互換性を上げる、といった具合です。出力品質がまだ不十分なら、request の具体内容と期待する JSON shape を追加して prompt を絞り込んでください。これは「もっとよくして」と曖昧に頼むより、たいていずっと効きます。