このエントリはMagento Advent Calendar 2019の5日目です。

前回はREST APIで利用できる認証方法と、それぞれの用途について解説しました。
今回は公式のDevdocsにあるAPIリファレンスをみながら、APIが要求するデータ型について触れていきたいと思います。

APIの活用にはデータ型の理解が不可欠

どんなWeb APIでも、やり取りするデータの形式は決まっているものです。
MagentoのREST APIもその例外ではなく、すべてのAPIに対して入出力するデータの形式が決まっています。
データの形式やそれぞれの項目の意味がわかっていれば、連携する側のシステムからどのようにデータを提供すればよいか考えることができるはずです。

幸い、公式のDevdocsには標準で用意されているAPIのリファレンスが下記のページで公開されています。

今回は管理者向けAPIリファレンスを見ながら理解を深めていきましょう。

APIリファレンスの読み方

管理者向けAPIリファレンスにアクセスすると、次のような画面が表示されます。

APIリファレンス

左ナビがAPI、右側にAPIの概要とレスポンスの例になっています。
この手のリファレンスは最近のWebサービスではよく見られるものなので見慣れている方も多いのではないでしょうか。

試しにカテゴリAPIを見てみることにしましょう。左ナビからcategoriesを探し、クリックすると次のような表示になります。

カテゴリAPI

この例では、/V1/categories のエンドポイントの定義を見ています。
左ナビにはPOSTとGETの2つのAPIがあることを示すリンクがあると思います。これは同じAPIでもPOSTとGETで異なる振る舞いをするAPIであることを意味しています。こういったAPIは他にもたくさんあるので、使用する際には注意しましょう。

APIの詳細

画面の中央にはAPIの詳細が表示されます。
「REQUEST BODY SCHEMA」や「QUERY PARAMETERS」にはAPIの用途とやり取りするデータ項目の説明が表示されます。

パラメータリスト

どの項目がどういった役割なのかが書かれているので、APIを使う前によく確認しましょう。
カテゴリAPIの場合はそこまで複雑ではないことがわかると思います。

リクエストとレスポンスのサンプル

右側にはリクエストデータのサンプルが表示されるので、データがどういう構造になっているかイメージしやすいと思います。

リクエストサンプル

リクエストサンプルの下にはレスポンスデータのサンプルも表示されます。HTTPレスポンスコードごとの例も示されているので、エラー制御の際に参考にすると良いでしょう。

レスポンスサンプル

APIリファレンスはすべて同じ形式で書かれているので、1つのAPIで読み方を理解すれば、他のすべてのAPIの定義内容を理解できるようになります。

APIとデータ項目の拡張

殆どのAPIは、Magento上で予め定義されているインターフェイス定義をもとにしています。
そのため、インターフェイス定義に存在しないデータは原則としてAPIでは触ることができません。

ただしこれには例外があり、extension_attributesについてはエクステンションで拡張することができます。先程のカテゴリAPIの例を見ると、extension_attributesという項目があると思います。これはカテゴリAPIがextension_attributesを用いて項目の追加が可能であることを意味しています。もちろんMagento側の実装が対応している必要がありますが、導入するサイトの要望に合わせて追加したデータ項目をAPI経由でやり取りする場合にextension_attributesを使えばAPI定義を変更しなくても拡張ができるということを意味しています。

なお、すべてのAPIのデータ型定義にextension_attributesがあるわけではないので、カスタマイズをする際にはAPI定義を確認してから行うようにしましょう。
うっかり項目追加をしてしまったあとでAPIの拡張ができないことに気がつくと、非常に切ない思いをします。

次回は

次回はMagento2.3から導入された、非同期APIについて解説します。
非同期APIを使うと大量のデータ更新がある場合でも一括して更新処理ができ、更新頻度の多いシステム連携で重宝します。