Aller au contenu principal

Intégration d'API Platform

API Platform est un framework permettant de créer et d'exposer une API directement à partir d'une application existante.

À quoi ça sert ?​

API Platform est réellement utile au sein d'une application, car elle a beaucoup de fonctionnalités nativement supportées :

API RESTFul​

Par défaut, API Platform pourra générer un CRUD complètement RESTFul sur une entité Doctrine par exemple. On pourra donc directement aller requêter l'API en utilisant les verbes HTTP correspondant aux différentes opérations qu'on souhaite effectuer sur la ressource.

Documentation Swagger/OpenAPI​

En plus de générer un CRUD, on pourra consulter une documentation Swagger/OpenAPI auto-générée, depuis le navigateur.

GraphQL​

À la base, API Platform expose une API REST aux clients. Il est également possible d'en faire une API GraphQL.

CORS & Authentification​

L'intégration du support CORS est nativement supportée à l'aide du package nelmio/cors-bundle, et l'authentification JWT peut être ajoutée très facilement avec le bundle lexik/jwt-authentication-bundle.

JSON-LD & Hydra​

JSON-LD signifie JSON for Linking Data. C'est un format permettant d'ajouter à nos ressources encore plus d'informations destinées aux machines qui vont accéder à notre API. API Platform intègre automatiquement des attributs supplémentaires au contenu JSON renvoyé par notre API, tels que @id pour identifier une ressource de manière unique avec son URI, ou encore @type explicitant le type d'une ressource, etc...

Hydra, en plus de JSON-LD, va ajouter encore plus d'informations à nos réponses. En réalité, Hydra définit tout un vocabulaire concernant les contenus Hypermedia. Hypermedia est le H dans HATEOAS (Hypermedia As The Engine Of Application State), ce principe REST indiquant qu'il peut être utile de fournir des informations permettant au client de continuer ses interactions avec l'API.

Ainsi, des informations hydra seront incluses automatiquement dans les réponses de notre API. Par exemple, si je veux une liste d'articles, alors des informations pour avoir la page suivante, la dernière page, le nombre total d'éléments seront intégrées :

{
  // Collection d'articles...

  "hydra:totalItems": 150,
  "hydra:view": {
    "@id": "/api/articles?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/api/articles?page=1",
    "hydra:last": "/api/articles?page=5",
    "hydra:next": "/api/articles?page=2"
  }
}

Installation et création de la première ressource​

Pour installer API Platform, on pourra utiliser son alias Flex api :

composer require api

Ensuite, dans l'entité Article, on va ajouter un attribut ApiResource pour créer automatiquement un CRUD REST :

use ApiPlatform\Metadata\ApiResource;
//...

#[ORM\Entity(repositoryClass: ArticleRepository::class)]
#[ApiResource]
class Article
{
}

On peut ensuite relancer le serveur et aller consulter la documentation derrière l'URL /api.

Api Platform 2.7 + Symfony 5

De gros changements ont eu lieu dans API Platform v2.7.

Le namespace ApiPlatform\Metadata a été introduit à ce moment-là. Pour que la ressource soit correctement détectée, il faut ajouter un paramètre dans le fichier de configuration d'API Platform :

config/packages/api_platform.yaml

api_platform:
  metadata_backward_compatibility_layer: false

  #...

API Platform OpenAPI Swagger UI

Groupes de sérialisation​

Si on teste directement un des endpoints présentés, on devra peut-être ajuster les groupes de sérialisation pour éviter une boucle infinie :

#[ApiResource(
  normalizationContext: ['groups' => ['articles:read']]
)]
class Article
{
}

On pourra ensuite utiliser ce groupe sur les propriétés de classes de notre choix.