API Platform Getting Started

API Platformのインストール

新しいプロジェクトを開始する場合、API プラットフォームを起動する最も簡単な方法は、API プラットフォーム ディストリビューションをインストールすることです。 Symfony フレームワーク、スキーマ ジェネレーター、Doctrine ORM、Elasticsearch-PHP、NelmioCorsBundle、および Behat と統合された API プラットフォーム コア ライブラリが付属しています。 Doctrine MongoDB ODM は、MongoDB のドキュメントに従って有効にすることもできます。基本的には、REST API を開発するための最適なツールと適切なデフォルト設定がパッケージ化された Symfony エディションです。

または、Composer を使用して、スタンドアロン バンドルを既存の Symfony Flex プロジェクトにインストールすることもできます。

composer require api

多くの設定が利用可能ですが、必須の構成オプションはありません。

Entityへのマッピング

API プラットフォームは、CRUD 操作をサポートする REST API を介して、「API リソース」としてマップされたエンティティを自動的に公開できます。エンティティを公開するには、Docblock 注釈、XML および YAML 構成ファイルを使用できます。

以下は、REST API を介して公開されるアノテーションを使用してマップされたエンティティの例です。

<?php
// api/src/Entity/Product.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Doctrine\Common\Collections\ArrayCollection;
use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Entity]
#[ApiResource]
class Product // The class name will be used to name exposed resources
{
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    private ?int $id = null;

    /**
     * A name property - this description will be available in the API documentation too.
     *
     */
    #[ORM\Column] 
    #[Assert\NotBlank]
    public string $name = '';

    // Notice the "cascade" option below, this is mandatory if you want Doctrine to automatically persist the related entity
    /**
     * @var Offer[]|ArrayCollection
     *
     */
    #[ORM\OneToMany(targetEntity: Offer::class, mappedBy: 'product', cascade: ['persist'])] 
    public iterable $offers;

    public function __construct()
    {
        $this->offers = new ArrayCollection(); // Initialize $offers as a Doctrine collection
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    // Adding both an adder and a remover as well as updating the reverse relation is mandatory
    // if you want Doctrine to automatically update and persist (thanks to the "cascade" option) the related entity
    public function addOffer(Offer $offer): void
    {
        $offer->product = $this;
        $this->offers->add($offer);
    }

    public function removeOffer(Offer $offer): void
    {
        $offer->product = null;
        $this->offers->removeElement($offer);
    }

    // ...
}

<?php
// api/src/Entity/Offer.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * An offer from my shop - this description will be automatically extracted from the PHPDoc to document the API.
 *
 */
#[ORM\Entity]
#[ApiResource(types: ['https://schema.org/Offer'])]
class Offer
{
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    private ?int $id = null;

    #[ORM\Column(type: 'text')]
    public string $description = '';

    #[ORM\Column]
    #[Assert\Range(minMessage: 'The price must be superior to 0.', min: 0)]
    public float $price = -1.0;

    #[ORM\ManyToOne(targetEntity: Product::class, inversedBy: 'offers')]
    public ?Product $product = null;

    public function getId(): ?int
    {
        return $this->id;
    }
}

これは、ハイパーメディア Web API を介して JSON-LD ドキュメントとして Product および Offer エンティティを公開するために必要な最小限の構成です。

Symfony エコシステムに精通している場合は、エンティティークラスが Doctrine ORM アノテーションと Symfony バリデーターコンポーネントからの検証制約にもマッピングされていることに気付きました。 これは必須ではありません。 好みの持続性と検証システムを使用できます。 ただし、API プラットフォームにはこれらのライブラリのサポートが組み込まれており、データを自動的に保持して検証するための特定のコードや構成を必要とせずにライブラリを使用できます。 これらは適切なデフォルト オプションであり、自分が何をしているのかわからない場合は、これらを使用することをお勧めします。

以前に行ったマッピングのおかげで、API プラットフォームは製品タイプのリソースに対して次の REST 操作を自動的に登録します。

offer メソッドでも同じ操作が可能です (ルートは /offers パターンで始まります)。ルート プレフィックスは、マップされたエンティティ クラスの名前を複数形にすることによって作成されます。操作パスの命名を使用して、命名規則をオーバーライドすることもできます。

アノテーションの代わりに、YAML または XML を使用してエンティティ クラスをマップできます。

# api/config/api_platform/resources.yaml
resources:
    App\Entity\Product: ~
    App\Entity\Offer:
        shortName: 'Offer'                   # optional
        description: 'An offer from my shop' # optional
        types: ['https://schema.org/Offer']   # optional
        paginationItemsPerPage: 25           # optional

アノテーションの代わりに YAML または XML ファイルを使用する場合は、適切なファイルをロードするように API プラットフォームを構成する必要があります。

# api/config/packages/api_platform.yaml
api_platform:
    mapping:
        paths: 
            - '%kernel.project_dir%/src/Entity' # default configuration for annotations
            - '%kernel.project_dir%/config/api_platform' # yaml or xml directory configuration

データのサブセットのみをシリアル化する場合は、シリアル化のドキュメントを参照してください。

これで、エンティティを公開する完全な機能を備えた API ができました。 Symfony ローカル Web サーバー (symfony server:start) で Symfony アプリを実行し、http://localhost:8000/api で API エントリポイントを参照します。

REST クライアント (Postman をお勧めします) または Hydra 対応アプリケーション (Hydra Console を試してみてください) を使用して API と対話します。 features ディレクトリにある使用例を見てみましょう。