Custom entities

In many cases, we are using Doctrine entities as base of our API. But sometimes, we need to extend the data model with custom entities. This can be done by creating a new class that acts like an entity. The new entity can be used in the same way as the built-in entities.

Our entities, custom controllers and providers are located in the src/API/CustomData directory.

Providers and controllers are an API Platform feature that allows you to customize the behavior of the API. Providers are used to provide data for the API (like the internal doctrine provider). Controllers are used to customize the behavior of the API. They are mostly used to add operations that are not the regular CRUD operations.

Each entity has an IRI (Internationalized Resource Identifier) that is used to identify the entity.

Entities

As mentioned above, custom entities work flawlessly with API Platform. All that is needed is to create a new class and annotate it with the necessary attributes. The following example shows how to create a custom entity:

<?php

namespace App\API\CustomData\RabbitMQ;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/rabbitmqs',
            normalizationContext: ['iri' => ''],
            provider: RabbitMQDataProvider::class

        ),
        new Get(
            uriTemplate: '/rabbitmqs/{identifier}',
            read: false,
            deserialize: false
        )
    ]
)]
class RabbitMQEntity
{
// ...   
}

The class RabbitMQEntity is a custom entity that is used in the API. The entity is annotated with the ApiResource attribute. The attribute contains two operations: GetCollection and Get. The GetCollection operation is used to retrieve a collection of RabbitMQEntity objects. The Get operation is used to retrieve a single RabbitMQEntity object.

The class is not a doctrine entity nor does it need to implement any interfaces. It is just a plain PHP class that is annotated with the ApiResource attribute.

Controllers

Controllers are mostly used to add operations that are not the regular CRUD operations. The following example shows how to create a custom controller:

#[ApiResource(
    operations: [
        new Get(
            uriTemplate: '/supervisors/restart',
            controller: SupervisorController::class,
            security: "is_granted('ROLE_ADMINISTRATOR')",
            securityMessage: "Access Denied: You don't have the rights to perform the action.",
            read: false,
            deserialize: false
        ),
    ]
)]
readonly class SupervisorEntity
{
// ...
}

The new Get operation is used to restart the supervisor. The pair of uriTemplate and controller attribute is used to specify the controller that is used to handle the request.

The controller class SupervisorController is a regular controller which returns a JsonResponse.

Providers

Custom providers must implement API Platform's ProviderInterface. The following example shows how to create a custom provider:

<?php

namespace App\API\CustomData\RabbitMQ;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;

/**
 * @implements ProviderInterface<RabbitMQEntity>
 */
class RabbitMQDataProvider implements ProviderInterface
{

    /**
     * @return RabbitMQEntity[]
     */
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): array
    {
        // Add an array of RabbitMQEntity objects.
        return $response;
    }
}