Le blog

API Platform 2.2 : Flex, GraphQL, JSON API, Kubernetes et bien plus

Publié le 01 février 2018

Retrouvez la version EN de cet article ici.

Nous sommes heureux de vous annoncer la sortie d’API Platform 2.2 beta 1 ! Cette nouvelle version arrive avec de nouvelles de fonctionnalités incluant :

Le support de GraphQL et JSON API ;
L'intégration de Symfony 4 / Flex ;
L'intégration de API Platform Admin (construit avec ReactJS et Admin On Rest) ;
L'intégration de générateurs de Progressive Web Apps en ReactJS et Vue.js (un générateur d’applications en React Native est aussi disponible) ;
Des containers Docker remaniés pour les composants Javascript et JS, incluant un support prêt à l’emploi pour HTTP2, HTTPS et un mécanisme d’invalidation de cache pour Varnish ;
La possibilité de déployer un cluster Kubernetes en quelques secondes ;
Une nouvelle façon extrêmement simple de déclarer des filtres à travers les annotations ;
Et une amélioration rigoureuse de la performance et la qualité.

La V2.2 est une des meilleures version d’API Platform jamais sorties, et probablement la solution “full-stack” la plus avancée pour créer des projets pilotés par des API.

Le changement de paradigme introduit dans cette nouvelle version a été détaillé lors de la conférence de Kévin Dunglas à la SymfonyCon Cluj 2017. Cela a pris 6 mois et 483 commits provenant d’une soixantaine de contributeurs pour bâtir cette nouvelle version. La documentation a également été nettement améliorée, même si elle reste évidemment perfectible (en mettant à jour le guide de démarrage et en migrant tous les articles vers la nouvelle structure de répertoires de Flex).

Un énorme merci à tous les contributeurs·trices de ce projet ! Passons désormais en revue toutes les nouvelles fonctionnalités :

La nouvelle distribution

La façon la plus simple de commencer à travailler avec API Platform a toujours été d’utiliser la configuration Docker fournie. Dans la version 2.2, la configuration Docker a été complètement repensée afin de concorder avec les nouvelles fonctionnalités fournies par Symfony Flex et pour intégrer nos composants Javascript.

Pour démarrer :

Téléchargez la dernière version ;
Dézippez l’archive et ouvrez un terminal dans le répertoire correspondant ;
Exécutez docker-compose up.

Vous obtiendrez : Un squelette d’API correspondant à la structure de Flex, où vous pourrez ajouter les classes modélisant votre modèle de données publiques afin d’obtenir une API hypermédia et/ou GraphQL fonctionnelle.

L’API est disponible en HTTP/2 et HTTPS grâce au proxy de développement fourni et bénéficie automatiquement du mécanisme de cache d’API Platform (le conteneur Varnish). Les headers CORS sont automatiquement configurés. Comme vous pouvez le constater, la documentation est - évidemment - disponible si vous ouvrez la page d’entrée dans un navigateur.

Home API Platform

Maintenant, saisissez docker-compose exec client generate-api-platform-client pour créer une Progressive Web App esthétique et complète utilisant React, Redux et Bootstrap 4.

Pour cela, le générateur analyse automatiquement la description de l’API hypermedia (au format Hydra) générée par le composant API.

Le générateur supporte également Vue.js, React Native et TypeScript, grâce aux contributions de Piotr Synowiec, Alain Hippolyte et Antoine Bluchet.

Lisez la documentation complète du générateur de client API Platform

Enfin et surtout, un admin généré dynamiquement pour l’API est également disponible :

Comme le générateur de client, le composant API Platform Admin tire parti de la documentation Hydra pour deviner automatiquement la structure de donnée exposée par l’API. Parce qu’il repose sur React et Admin On Rest (aka React Admin), API Platform est entièrement personnalisable. Morgan Auchedé est le nouveau mainteneur de ce composant, et l’a considérablement amélioré depuis sa première sortie officielle.

Dans cette version d’API Platform, le conteneur MySQL a été remplacé par un Postgres.

Déploiement Kubernetes instantané

Kubernetes est devenu la solution la plus populaire pour exécuter, déployer et gérer ses conteneurs en production. Google Cloud Platform, Microsoft Azure et Amazon Web Services fournissent des environnement de développement gérés par Kubernetes. API Platform 2.2 comporte un chart Helm (le manager de packages de K8s) intégré pour déployer avec facilité :

helm upgrade --install ./api/helm/api 
    --set php.repository=gcr.io/test-api-platform/php 
    --set nginx.repository=gcr.io/test-api-platform/nginx 
    --set secret=MyAppSecretKey 
    --set postgresql.postgresPassword=MyPgPassword 
    --set postgresql.persistence.enabled=true 
    --set corsAllowUrl='^https?://[a-z]*.mywebsite.com

Votre app est désormais exécutée dans un cluster ! Consultez la documentation à ce sujet pour découvrir plus de détails sur ce chart.

Support de GraphQL

GraphQL est un langage de requêtes conçu par Facebook proposant une alternative aux API Rest. Son support était une des fonctionnalités les plus demandées pour API Platform, et c’est désormais le cas ! Le nouveau sous-système GraphQL d’API Platform supporte désormais :

100% des principales spécifications, incluant les requêtes et mutations.
100% de la spécification serveur relais de GraphQL (et qui est compatible avec aussi bien les clients Relay et Apollo GraphQL)
La pagination
Les filtres (intégrés et personnalisés)
La validation
Les règles de contrôles d’accès
La génération de requêtes SQL optimisées (jointures automatiques en fonction des données demandées)
L'UI GraphiQL

Pour activer le support de GraphQL, vous devez seulement installer la bibliothèque PHP GraphQL :

docker-compose exec php composer req webonyx/graphql-php

Ensuite, créez une entité API Platform :

namespace AppEntity;

use ApiPlatformCoreAnnotationApiResource;
use DoctrineORMMapping as ORM;
use SymfonyComponentValidatorConstraints as Assert;

/**
 * An organization.
 *
 * @ApiResource
 * @ORMEntity
 */
class Organization
{
    /**
     * @ORMId
     * @ORMColumn(type="guid")
     * @AssertNotBlank
     */
    public $id;
    /**
     * @ORMColumn(type="text")
     * @AssertNotBlank
     */
    public $name;
}

Effectivement, les formats GraphQL et REST peuvent être utilisés pour la même entité ! Grâce au support hypermedia d’API Platform, vous pouvez même exécuter une requête GraphQL et ensuite appliquer des opérations REST aux ressources récupérées pour la même entité en utilisant leurs IRIs.

Votre API GraphQL est prête ! Rendez-vous sur : https://localhost:8443/graphql

API Platform GraphQL" title="API Platform GraphQL

Il y a encore beaucoup de choses à dire sur le support de GraphQL, et comment l’utiliser avec REST et JSON-LD. Un article dédié sera prochainement posté à ce sujet. Le support de GraphQL n’aurait pas été possible sur cette version sans le travail conséquent de Raoul Clais, Alan Poulain, Baptiste Meyer et Kévin Dunglas.

Support de JSON API

JSON API est un format hypermedia très prometteur. Contrairement à JSON-LD (le format par défaut exposé par API Platform), ce n’est pas un standard web et il a moins de fonctionnalités (pas de compatibilité RDF par exemple). Il est également plus simple à apprendre et comprendre. Avec API Platform 2.2, vous n’avez pas à choisir, vous pouvez avoir les deux et encore plus puisque notre framework supporte JSON-LD/Hydra, HAL, JSON API, YAML, XML, raw JSON et comme vous avez pu le constater, GraphQL.

Pour activer JSON API, saisissez la configuration suivante :

# config/packages/api_platform.yaml
api_platform:
  # ...
  formats:
    # ...
    jsonapi: ['application/vnd.api+json']
  error_formats:
    # ...
    jsonapi: ['application/vnd.api+json']

Facile, n’est-ce-pas ? Le support de JSON API a été élaboré par Hamza Amrouche, Hector Hurtarte et Baptiste Meyer.

Déclarer des filtres en utilisant les annotations

Le système de filtres d’API Platform est très puissant. Il comporte un nombre conséquent de filtres intégrés, il peut être facilement étendu mais jusqu'à présent, ce système n’était pas vraiment simple à configurer car il fallait déclarer les services manuellement.

Alors que Symfony Flex se concentre sur l'auto-configuration et l'autowiring, il était important de simplifier la configuration des filtres. Antoine Bluchet a réalisé une méthode simple pour le faire en utilisant les annotations.

<?php

namespace AppEntity;

use ApiPlatformCoreAnnotationApiFilter;
use ApiPlatformCoreAnnotationApiResource;
use ApiPlatformCoreBridgeDoctrineOrmFilterSearchFilter;
use DoctrineORMMapping as ORM;
use SymfonyComponentValidatorConstraints as Assert;

/**
 * An organization.
 *
 * @ApiResource
 * @ORMEntity
 */
class Organization
{
    /**
     * @ORMId
     * @ORMColumn(type="guid")
     * @AssertNotBlank
     */
    public $id;

    /**
     * @ORMColumn(type="text")
     * @AssertNotBlank
     * @ApiFilter(SearchFilter::class)
     */
    public $name;
}

Rien de plus à déclarer, vous pouvez désormais filtrer la collection d’organisation par le nom de propriété, et avec REST et GraphQL !

En plus de ces principales fonctionnalités, beaucoup d’autres options de configuration et améliorations ont été ajoutées. Lisez le changelog entier pour en savoir plus :

Si vous appréciez API Platform, suivez le projet sur Twitter et mettez une étoile sur Github.

Depuis API Platform 2.2, la commande Symfony Thanks est également incluse. Grâce à cet outil, vous pouvez envoyer un remerciement par le biais d’une étoile à toutes les bibliothèques PHP que vous utilisez (y compris API Platform) en effectuant la commande suivante : docker-compose exec php composer thanks.

Si vous voulez apprendre à utiliser API Platform, n’hésitez pas à consulter nos formations sur notre site dédié ou alors venez assister à un des nombreux workshops organisés prochainement :

Don’t miss the next opportunities to learn @ApiPlatform during a 1 day workshop:
- « Creating and deploying API Platform apps on @platformsh » / @APIdaysGlobal
- « Mastering the API Platform’s server component » / @symfony_live Paris (2 sessions) then Phantasialand
— Kévin Dunglas (@dunglas) 23 janvier 2018