General Design Considerations

Since you only need to describe the structure of the data to expose, API Platform is both a "design-first" and "code-first" API framework. However, the "design-first" methodology is strongly recommended: first you design the public shape of API endpoints.

公開するデータの構造を記述するだけでよいため、API プラットフォームは「デザイン ファースト」かつ「コード ファースト」の API フレームワークです。ただし、「デザイン ファースト」の方法論を強くお勧めします。まず、API エンドポイントのパブリック シェイプをデザインします。

To do so, you have to write a plain old PHP object (POPO) representing the input and output of your endpoint. This is the class that is marked with the #[ApiResource] attribute. This class doesn't have to be mapped with Doctrine ORM, or any other persistence system. It must be simple (it's usually just a data structure with no or minimal behaviors) and will be automatically converted to Hydra, OpenAPI and GraphQL documentations or schemas by API Platform (there is a 1-1 mapping between this class and those docs).

そのためには、エンドポイントの入力と出力を表すプレーン オールド PHP オブジェクト (POPO) を作成する必要があります。これは、#[ApiResource] 属性でマークされたクラスです。このクラスは、Doctrine ORM やその他の永続化システムにマップする必要はありません。シンプルである必要があり (通常は動作がまったくないか最小限のデータ構造です)、API プラットフォームによって Hydra、OpenAPI、GraphQL のドキュメントまたはスキーマに自動的に変換されます (このクラスとドキュメントの間には 1 対 1 のマッピングがあります)。

Then, it's up to the developer to feed API Platform with an hydrated instance of this API resource object by implementing the ProviderInterface. Basically, the state provider will query the persistence system (RDBMS, document or graph DB, external API...), and must hydrate and return the POPO that has been designed as mentioned above.

次に、開発者は、ProviderInterface を実装して、この API リソース オブジェクトのハイドレートされたインスタンスを API プラットフォームにフィードします。基本的に、状態プロバイダーは永続化システム (RDBMS、ドキュメントまたはグラフ DB、外部 API など) にクエリを実行し、ハイドレートして上記のように設計された POPO を返す必要があります。

When updating a state (POST, PUT, PATCH, DELETE HTTP methods), it's up to the developer to properly persist the data provided by API Platform's resource object hydrated by the serializer. To do so, there is another interface to implement: ProcessorInterface.

状態 (POST、PUT、PATCH、DELETE HTTP メソッド) を更新する場合、開発者は、シリアライザーによってハイドレートされた API プラットフォームのリソース オブジェクトによって提供されるデータを適切に永続化する必要があります。

This class will read the API resource object (the one marked with #[ApiResource]) and:

このクラスは、API リソース オブジェクト (#[ApiResource] でマークされたオブジェクト) を読み取ります。

  • persist it directly in the database;
  • or hydrate a DTO then trigger a command;
  • or populate an event store;
    またはイベント ストアに入力します。
  • or persist the data in any other useful way.

The logic of state processors is the responsibility of application developers, and is out of the API Platform's scope.

ステート プロセッサのロジックはアプリケーション開発者の責任であり、API プラットフォームの範囲外です。

For Rapid Application Development, convenience and prototyping, if and only if the class marked with #[ApiResource] is also a Doctrine entity, the developer can use the Doctrine ORM's state provider and processor implementations shipped with API Platform.

ラピッド アプリケーション開発、利便性、プロトタイピングのために、#[ApiResource] でマークされたクラスが Doctrine エンティティでもある場合に限り、開発者は DoctrineORM の状態プロバイダーと API プラットフォームに同梱されているプロセッサの実装を使用できます。

In this case, the public (#[ApiResource]) and internal (Doctrine entity) data models are shared. Then, API Platform will be able to query, filter, paginate and persist data automatically. This approach is super-convenient and efficient, but is probably not a good idea for non-CRUD and/or large systems. Again, it's up to the developers to use, or to not use these built-in state providers/processors depending on the business logic they are dealing with. API Platform makes it easy to create custom state providers and processors. It also makes it easy to implement patterns such as CQS or CQRS thanks to the Messenger Component integration and the DTO support.

この場合、パブリック (#[ApiResource]) と内部 (Doctrine エンティティ) のデータ モデルが共有されます。その後、API プラットフォームは自動的にデータのクエリ、フィルタリング、ページ分割、永続化を行うことができます。このアプローチは非常に便利で効率的ですが、CRUD 以外のシステムや大規模なシステムには適していない可能性があります。 API プラットフォームを使用すると、カスタムの状態プロバイダーとプロセッサを簡単に作成できます。また、CQS や CQRS などのパターンを簡単に実装できます。 Messenger コンポーネントの統合と DTO サポート。

Last but not least, to create Event Sourcing-based systems, a convenient approach is:

最後になりましたが、イベント ソーシング ベースのシステムを作成するための便利な方法は次のとおりです。

  • to persist data in an event store using a Messenger handler or a custom state processor
    Messenger ハンドラまたはカスタム状態プロセッサを使用してイベント ストアにデータを保存する
  • to create projections in standard RDBMS (PostgreSQL, MariaDB...) tables or views
    標準 RDBMS (PostgreSQL、MariaDB...) テーブルまたはビューでプロジェクションを作成する
  • to map those projections with read-only Doctrine entity classes and to mark those classes with #[ApiResource]
    これらのプロジェクションを読み取り専用の Doctrine エンティティ クラスにマップし、それらのクラスを #[ApiResource] でマークする

You can then benefit from the built-in Doctrine filters, sorting, pagination, auto-joins and all of the extension points provided by API Platform.

その後、組み込みの Doctrine フィルター、並べ替え、ページネーション、自動結合、および API プラットフォームによって提供されるすべての拡張ポイントを利用できます。