WP REST API のドキュメント内の用語集を簡単に翻訳する

WP REST API の公式のドキュメンテーションサイトにある用語集を翻訳してみました。コントローラ、HEAD, GET, POST, PUT, DELETE、HTTP Client、Resource、Routes、Endpoints、Schemaの項目があります。

Glossary | WP REST API v2 Documentation は WordPress JSON REST API の用語集となっておりまして、ここを翻訳してみたいと思います。

時期が来たら日本語のコデックスに移動したらいいかな?と思うけど日本語の使い方が難しいので困っちゃうな。ちゃんとやろうとするとすごく時間がかかってしまうので。。。

以下、翻訳です。

用語集

REST API の初心者ですか?このドキュメンテーションで使われているフレーズを理解してスピードアップだ!

コントローラ

Model-View-Controller はソフトウェア開発における標準パターンです。よく分からない方は、少し勉強すると先に進むのが速くなると思います。

WP-API には、コントローラのコンセプトが取り入れられており、WP-API のリソース(後述)エンドポイント(後述)を表すクラスに対する標準化されたパターンがあります。すべてのリソースエンドポイントは、 WP_REST_Controllerクラスを継承しており、共通のメソッドが利用できます。

HEAD, GET, POST, PUT, DELETE リクエスト

これらの “HTTP verbs (http 動詞)” は、

  • HTTPクライアントが、
  • リソースに対して、
  • 実行しようとするアクションのタイプ

を表します。たとえば、 GET リクエストは投稿のデータを取得するために使われ、 DELETE リクエストは投稿を削除するために使われる、というようなこと。これらの語はまとめて HTTP verbs と呼ばれており、それは web に置いて標準化されたものです。

WordPress の関数に慣れ親しんでいる人であれば、 GET は wp_remote_get() に、POSTwp_remote_post() に対応すると言えます。

HTTP クライアント

“HTTP クライアント”とは、WP-API と関わるためにあなたが利用するツールのことを指します。

を使ってリクエストをテストすることができます。(ターミナルの httpie なら本ブログのこの本ブログのこの記事も読んでみてね。

WordPress 自身も HTTP クライアントを提供しており、 WP_HTTP_CLASS とその関連関数群(たとえば wp_remote_get() )などがあります。

リソース

リソースとは、WordPress 内の discrete entity (個別の離散的な実体 – この難しい言葉、なんだろw) のことです。Posts, Pages, Comments, Users, Terms などのことで、あなたもすでに知っているものです。

ひっしーに教えてもらいました。

スクリーンショット 2016-01-03 10.28.38

WP-API は、

  • HTTP クライアントに、
  • こうしたリソースに対する
  • CRUD の実行(Create, Read, Update, Delete)を許可します。

具体的にどのように WP-API リソースとインタラクトするのかを見てみましょう。(意訳。WP-APIを通じて、投稿とかユーザーとか(リソース!)と関わる事例は以下)

GET /wp-json/wp/v2/posts

投稿のリストを取得。WP_Query に対応すると思って良い。

GET /wp-json/wp/v2/posts/123

ID が 123 である投稿の取得。 get_post()に対応すると思ってよし。

POST /wp-json/wp/v2/posts

新規投稿。 wp_insert_post() のような感じ。

DELETE /wp-json/wp/v2/posts/123

ID が 123 の投稿を削除。概ね wp_delete_post() と言える。

Routes ルート / Endpoints エンドポイント

エンドポイントとは、 API を通して利用可能な関数・機能のことで、たとえば、 API のインデックスを取得したり、投稿を更新したり、コメントを削除したりということが可能です。エンドポイントは、いくつかのパラメータを受け付けて特定の関数を実行し、クライアントにデータを返します。

ルートとは、エンドポイントにアクセスするための”名前”のことで、URL の形で利用されます。ひとつのルートは複数のエンドポイントと関連付けられることが可能です。どのエンドポイントに関連付けられるのかは、 HTTP verbs に依って変わります。

たとえば、http://example.com/wp-json/wp/v2/posts/123 というURLがあったとすると、

  • ルートは wp/v2/posts/123 となります。ルートは wp-json を含みません。なぜなら、 wp-json は API 自身の bath path (土台となるパス)  であるからです。
  • このルーツは3つのエンドポイントを持っています。
    • GET は投稿データをクライアントに返す、 get_item メソッドのトリガーとなります。
    • PUT は更新のためのデータを受け取り、更新された投稿データを返す update_item メソッドのトリガーとなります。
    • DELETEdelete_item メソッドを発火させ、消したばかりの投稿データをクライアントに返します。

註: pretty permalink を有効にしていないサイトでは、ルートは rest_route パラメータとして URL に追加されます。上記の事例で言えば、 http://example.com/?rest_route=wp/v2/posts/123 がその場合の完全な URL となります。

スキーマ

スキーマとは、 WP-API のレスポンスデータの形式(フォーマット)を表す言葉です。たとえば、Post スキーマは、Post が id, title, content, author、その他のフィールドを返すようにリクエストを伝達します。WP-API のスキーマは、各フィールドのタイプや人間に理解可能なディスクリプション、フィールドが返されるコンテクストも表示します。

翻訳ここまで。親切、かつ抽象的な説明ですね。頭の中に浸透するまでに時間がかかるかなと思います。これから諸々のチュートリアルを試してみたり、質問を送ったり自分で色々考えていくにあたって、大事なところ。訳語については、僕にとって新しいところも多いので、英語のまま残していたりカタカナにしたり日本語にしたり混ぜたりしています。僕と同様にこうした分野が初めての人が多いと思いますので、ちょっとずつ共通の言語を増やしていかないとですね。フィードバックは @shinichiN に送ってくれると反応が速いです。

↓ プラグインを作る方々への本、書きました。 ↓

“WP REST API のドキュメント内の用語集を簡単に翻訳する” への 2 件のフィードバック

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です