Adobe Commerce / Magento Open Sourceで独自のREST APIエンドポイントを作成するには〜その2

今回は「Adobe Commerce / Magento Open Sourceで独自のREST APIエンドポイントを作成するには〜その1」の続きとして、webapi.xmlで宣言したInterfaceとその対になるクラスの実装方法について解説していきたいと思います。
API用に実装をする場合は、通常の実装と少々変わるところがあるので注意が必要です。

Interfaceの定義

REST APIを自作するためには、次の2種類のInterfaceを定義する必要があります。

  • エンドポイントに使用するInterface
  • データ型に使用するInterface

若干面倒な作業ではありますが、これにはきちんと理由があります。
順番に説明していきましょう。

今回使用するREST APIエンドポイントの内容

今回はサンプルとして、以下のようなエンドポイント定義を作成してみることにします。

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route url="/V1/example/endpoint/info" method="GET">
        <service class="Veriteworks\Webapi\Api\InfoInterface" method="getSampleInfo"/>
        <resources>
            <resource ref="anonymous" />
        </resources>
    </route>

    <route url="/V1/example/endpoint/info" method="POST">
        <service class="Veriteworks\Webapi\Api\InfoInterface" method="setSampleInfo"/>
        <resources>
            <resource ref="anonymous" />
        </resources>
    </route>
</routes>

この定義例では、以下の内容で2つのエンドポイントを定義しています。

  • GET /V1/example/endpoint/info で何かが得られるAPI
  • POST /V1/example/endpoint/info で何かの値をセットするAPI
  • Veriteworks\Webapi\Api\InfoInterface::getSampleInfo がGET側の処理を担当
  • Veriteworks\Webapi\Api\InfoInterface::setSampleInfo がPOST側の処理を担当
  • 権限の制限は設けない

Interfaceを定義する

では、Interfaceを定義しましょう。
REST APIの実装をするためには、Magentoフレームワークの仕様に基づいたエクステンションの開発方法を理解している必要があります。
できれば本記事を読まれる前に一通りの手順をマスターいただくとよいでしょう。

APIディレクトリの作成

最初に行うことはAPIディレクトリの作成です。
APIディレクトリは

エクステンションディレクトリ/Api

に作成することとなっています。
（絶対ではありませんが、ほとんどのエクステンションが同じ構成を取っています）

APIに使うInterfaceの定義

では次にInterfaceの定義を行いましょう。
InfoInterface.phpをApiディレクトリの直下に作成します。
定義内容は一旦以下の通りとします。

<?php
namespace Veriteworks\Webapi\Api;

interface InfoInterface
{
    /**
     * @return Data\InfoInterface
     */
     public function getSampleInfo(): Data\InfoInterface;

    /**
     * @param Data\InfoInterface $info
     * @return int
     */
     public function setSampleInfo(Data\InfoInterface $info) : int;
}

引数の型に注意

先程の例では脈絡なくData\InfoInterfaceが出てきました。これについて少し説明しましょう。

REST APIでパラメータをやり取りする場合、intやstringのようなデータ型の場合はまだいいのですが、オブジェクトとして受け渡しをしたい場合は工夫が必要です。

単純な配列だったとしても、Magentoフレームワークとしては何かしらのオブジェクト型変数であることが求められる仕様になっています。
このオブジェクト型変数が持っているGetter/Setterメソッドを定義するために、

エクステンションディレクトリ/Api/Data

下にデータ型のInterfaceを定義します。

Data\InfoInterfaceはそういったREST APIでやり取りするデータ型に使用するInterfaceです。
このInterface定義とその対になるModel実装をうっかり忘れ、引数の型にarrayを指定してしまうとエラーになってしまいます。注意しましょう。

データ型に使用するInterfaceの定義

というわけで、データ型に使用するInterfaceを定義しましょう。
先ほど挙げたパスに、下記の内容のInterfaceを作成します。

<?php
namespace Veriteworks\Webapi\Api\Data;

interface InfoInterface
{
    /**
     * @param string $label
     * @return InfoInterface
     */
     public function setLabel(string $label): InfoInterface;

    /**
     * @return string
     */
     public function getLabel(): string;

    /**
     * @param int $value
     * @return InfoInterface
     */
     public function setValue(int $value): InfoInterface;

    /**
     * @return int
     */
     public function getValue(): int;
}

これでデータ型のInterface定義ができました。

次回はこのInterfaceに対してModel実装を追加し、実際にREST APIを動かしてみたいと思います。