3 - Exposer des données avec ApiPlatform

Getting Started With API Platform with Symfonyapi-platform.com

La doc oficielle

Start up

Comme souvent, tout commence par l'installation d'un package:

composer require api

ApiPlatform à l'énorme avantage d'être 100% intégré à l'écosystème Symfony (et donc Doctrine).

Par défaut, pour transformer une Entity en ressource Api, il vous suffit d'une ligne de code à ajouté sur votre entité.

Exemple pour notre entité User, qui ressemble actuellement à:

<?php

namespace App\Entity;

use App\Doctrine\Traits\UuidTrait;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;

#[ORM\Entity]
#[ORM\UniqueConstraint(name: 'UNIQ_USER_IDENTIFIER_EMAIL', fields: ['email'])]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    use UuidTrait;

    #[ORM\Column(length: 180)]
    public ?string $email = null;

    #[ORM\Column]
    public array $roles = [];

    #[ORM\Column]
    public ?string $password = null;

    public function __construct()
    {
        $this->defineUuid();
    }

    public function getUserIdentifier(): string
    {
        return (string)$this->email;
    }

    public function getRoles(): array
    {
        $roles = $this->roles;
        $roles[] = 'ROLE_USER';

        return array_unique($roles);
    }

    public function getPassword(): ?string
    {
        return $this->password;
    }

    public function eraseCredentials(): void
    {
    }
}

Il suffit de lui ajouter une annotation pour la transformer en une API complète:

<?php

use ApiPlatform\Metadata\ApiResource;

#[ApiResource] # cette annotation nous transforme en API
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    ....
}

Vous venez de dire à ApiPlatform que votre User est une API.

En interne, ApiPlatform fait plusieurs choses:

1. Il "crée" tous les controllers pour la gestion de vos Users (création/édition/suppression)

2. Il défini une documentation propre (visible sur /api/docs)

Exemple de la doc

Vous pouvez ainsi appeler /api/users et avoir la liste de tous vos utilisateurs:

{
    "@context": "/api/contexts/User",
    "@id": "/api/users",
    "@type": "Collection",
    "totalItems": 1,
    "member": [
        {
            "@id": "/api/users/69b73d4d-b9b7-4b00-845f-726933b2224c",
            "@type": "User",
            "email": "[e-mail]",
            "roles": [
                "ROLE_USER"
            ],
            "password": "$2y$13$H077DPLf7W1/7kFbokX2Ius7T8EuvhluNCRqY906ssd3hiNA51PnO",
            "uuid": "69b73d4d-b9b7-4b00-845f-726933b2224c",
            "userIdentifier": "[e-mail]"
        }
    ]
}

On peut voir ici un premier soucis: le mot de passe ressort dans notre API. Même s'il est crypté, on ne devrait pas le renvoyer.

Pour cela on peut utiliser deux méthode lié au Serializer Symfony:

• Les groups de sérialization

• L'attribut de serialization #[Ignore]

Exemple avec l'attribut:

<?php

...

use Symfony\Component\Serializer\Attribute\Ignore;

#[ApiResource]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    ...
    #[ORM\Column]
    #[Ignore] # Cet attribut
    public ?string $password = null;
    ...
}

Le password sera désormais ignoré dans votre API (que ce soit en lecture ou en écriture)

Il est possible d'avoir plus de granularité via l'attribut ApiProperty:

<?php

...

use ApiPlatform\Metadata\ApiProperty;

#[ApiResource]
class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    ...
    #[ORM\Column]
    #[ApiProperty(writable: false, readable: true)]
    public ?string $email = null;
    ...
}

Par exemple, dans notre cas, on précise que la propriété email est uniquement readable.

Cette attribut ne gère pas que ça, n'hésitez pas à l'explorer plus en profondeur !

Limiter les opérations exposés

Par défaut, l'attribut #[ApiResource] expose toutes les requête REST existantes:

• Deux en méthode GET:

  • Une pour récupérer une collection (/api/users)

  • Une pour récupérer un objet en particulier: (/api/users/{uuid})

• Une méthode POST: Pour créer un objet (/api/users)

• Une méthode PATCH: Pour modifier partiellement un objet (/api/users/{uuid})

• Une méthode PUT: Pour modifier complètement un objet (/api/users/{uuid})

• Une méthode DELETE: Pour supprimer complètement un objet (/api/users/{uuid})

C'est changeable on appliquant seulement les requêtes que l'on souhaite:

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Delete;

#[Get]
#[GetCollection]
#[Post]
#[Put]
#[Delete]
class User
{
}