La première alpha d’API Platform 2.0 est disponible !

Il y a presque un an - déjà ! -, nous vous présentions API Platform, un framework PHP construit sur Symfony pour les projets API-First dont nous sommes les créateurs. Quelques mois après le lancement de la première version stable, API Platform 1.0, nous sommes heureux de vous annoncer que la première alpha d’API Platform 2.0 est enfin disponible ! À cette occasion, nous vous proposons de découvrir les changements et les nouvelles fonctionnalités apportés par cette version.

Avant de commencer, un petit rappel s’impose. API Platform est un framework qui permet de créer en quelques minutes des API Web modernes complètes et puissantes avec une liberté totale en termes de redéfinition et de personnalisation. Il est conforme avec la dernière génération de normes et d’usages : il supporte les Linked Data, HATEOAS et le web sémantique (JSON-LD, Hydra, Schema.org, JWT…).

La version 1.1 d’API Platform a été dévoilée le 16 mai dernier. Elle n’apporte pas de nouvelles fonctionnalités mais corrige quelques bugs et améliore la sécurité. Cette version est construite sur Symfony 2.8 mais elle est parfaitement compatible avec Symfony 3.0. Elle sera maintenue jusque novembre 2019 (tout comme Symfony 2.8).

La première alpha d’API Platform 2.0 est disponible depuis la même date. Sa version stable est prévue pour le mois de juin.

En quelques mois d’existence, API Platform a récolté plus de 650 étoiles sur GitHub. Le framework compte 5 membres dans sa Core Team (Samuel Roze, Teoh Han Hui, Théo Fidry, Vincent Chalamon et Kévin Dunglas) et plus de 60 contributeurs. Des entreprises de toutes tailles l’utilisent déjà dans le cadre de leurs projets : c’est notamment le cas de SensioLabs, Smile, La Fourchette/TripAdvisor ou encore BeIN Sports.  

API Platform 2.0 n’est pas une réécriture complète. Cette version corrige quelques limites de conception présentes dans la version 1 mais n’est plus rétrocompatible.   

API Platform Core (anciennement DunglasApiBundle) n’est plus un bundle Symfony mais une bibliothèque PHP indépendante construite avec des composants Symfony. Elle est utilisable en PHP brut (le support de Laravel ne devrait pas tarder) mais Symfony est toujours (et restera) le choix privilégié (bundle inclus).

Cette version implémente le modèle Action-Domain-Responder en utilisant les événements du kernel Symfony. Il est plus flexible et plus facile à personnaliser.

L’utilisation de PHP 7+ permet l’utilisation des nouvelles fonctionnalités comme l’opérateur ??, les type-hints scalaires et les types de retour dans le code d’API Platform.

Dans Symfony 3.1+, une bonne partie du code d’API Platform v1 été déplacé dans les composants Serializer, PropertyInfo et PropertyAccess de Symfony.

composer create-project api-platform/api-platform myapp v2.0.0-alpha.1

git clone git@github.com:api-platform/core.git && cd core && docker-compose up

API Platform 2.0 introduit le support du XML. Il reste encore à ajouter le support du mapping des propriétés. Cette version supporte également le format YAML. Là encore, il reste à ajouter le support du mapping des propriétés. Le nouveau système de configuration d’API Platform 2.0 permet également la pagination, les relations, le tri ou encore le filtrage. 

Les filtres disponibles (Doctrine) sont les suivants :

Vous pouvez personnaliser les opérations et groupes de sérialisation. Seules les opérations GET /tasks et GET /tasks{id} sont disponibles. Toutes les autres opérations (POST, PUT, DELETE) ne sont pas enregistrées. Lorsque vous utilisez cette configuration, les déclarations doivent être explicites.

Différents groupes de sérialisation sont appliqués par opération. Seul « text » est affiché dans la liste, « text » et « status » sont affichés pour l’IRI de l’item et la désérialisation n’est pas impactée (utilisez la clef denormalization_context).

Cela fonctionne également avec les mappings XML et YAML.

Le système d’événements de la version 1 a été retiré (PRE_CREATE, POST_CREATE, PRE_VALIDATE…). API Platform 2.0 s’appuie sur les événements Symfony. Cette version implémente également le modèle Action-Domain-Responder. Les Event Listeners sont appliqués uniquement sur les requêtes gérées par API Platform (et non sur les requêtes Symfony standards). Pour hooker votre logique personnalisée, vous pouvez utiliser les événements kernel : sécurité (isGranted), en-tête de cache, validation, persistence, appel à des API externes, mail…

La requête kernel.request permet de deviner le meilleur format de réponse (négociation de contenu).

La requête controller permet de :

Kernel.view (priorité 20) valide les données (POST, PUT). En priorité 10, elle permet de faire persister les données (POST, PUT, DELETE) et en priorité 0, elle sérialise les données et les transforme dans une réponse.

L’utilisation des opérations et des contrôleurs personnalisés permet de créer des extrémités orientées services ou non REST. Elle permet également de personnaliser les URLs et de gérer les sous-ressources (exemple : /tasks/{id}/comments/{c_id}). Quand les événements kernel ne suffisent pas, hookez votre propre logique, mais préférez toujours les événements kernel lorsque cela est possible.

Les autres points d’extension (qui existent également dans la v1) sont les suivants :

La négociation de contenu offre la possibilité de sélectionner le meilleur format à utiliser selon le header HTTP Accept.  Elle est construite sur la bibliothèque Negotiation 2 de William Durand (comme FOSRest) et se connecte au composant Serializer de Symfony. Elle permet de retourner des formats hypermédia (HAL, JSON-API…) ou non (JSON brut, XML brut…).

La version 1.1 du générateur de schéma est incluse dans API Platform 1.1 et 2. Il est disponible en PHAR et est compatible avec Symfony 3. Il supporte :

Il peut exploiter n’importe quel vocabulaire RDF(a) et permet de personnaliser les attributs unique, nullable et l’annotation @Column de Doctrine.

API Platform 2.0 introduit le support de MongoDB (WIP), la pagination (configurable et avec un nouveau format Hydra), la gestion des relations, la sérialisation des types complexes (comme les objets imbriqués) et le support de PSR-6 pour de meilleures performances. Cette version comprend également de nouveaux filtres.   

Le composant Serializer de Symfony 3.1 introduit la sérialisation des objets imbriqués, la sérialisation des arbres avec l’annotation @MaxDepth, le normalizer data: URl vers SplFileInfo pour l’upload de fichiers et le normalizer d’objets DateTime. Sa performance est améliorée, notamment avec le support de PSR-6.  

Au niveau des outils côté client, il faut encore améliorer le bridge ng-admin/Hydra, qui est pour l’instant en alpha, et l’admin Hydra Angular 2 (en cours).  Il reste également à intégrer Guzzle et à créer des générateurs CRUD Angular 2, React, Vue.js etc. en utilisant la documentation Hydra.

Il faut aussi ajouter le support de JSONAPI et HAL (rien de bien compliqué grâce à la nouvelle architecture d’API Platform) et de Swagger 2.0.

Si vous souhaitez contribuer au projet, n’hésitez pas ! Nous avons besoin de votre aide pour :

Un grand merci à tous ceux qui participent activement au développement d’API Platform. Stay tuned pour la suite des événements !