Sortie d'API Platform V2 !

Retrouvez la version originale [EN] de cet article ici.

Après une année de développements et plus de 700 commits réalisés par plus d’une centaine de contributeurs à travers le monde, la nouvelle version d’API Platform est désormais disponible en téléchargement !

API Platform est un framework en PHP7 destiné à la création d’API web modernes, puissantes et sécurisées. Cet outil est parfaitement adapté à la construction de systèmes d’informations API-centric basés sur l’hypermedia et les Linked Data. Il s'applique également à la réalisation de Single-Page Applications (en utilisant des bibliothèques Javascript telles que React ou Angular) et d’applications mobiles.

API Platform repose sur 3 principes fondateurs  :

API Platform v2 est une réécriture profonde du framework incluant une refonte complète de la conception, des ajouts de nouvelles fonctionnalités et des corrections de bugs. Faisons le point sur ces changements et les nouvelles fonctionnalités majeures :

Grâce au nouveau système de configuration et au composant de métadonnées (la couche d’abstraction entre les différents formats supportés), vous pouvez créer une API hypermedia de qualité simplement en modélisant vos données sous forme de classes PHP et en ajoutant quelques annotations.

Exemple :

Cette classe est suffisante pour obtenir une API fonctionnelle, supportant les fonctionnalités suivantes :

Consultez notre démo pour tester un exemple plus avancé (code source de seulement 2 classes) !

Les relations hypermédias entre les différentes ressources exposées par l’API sont gérées nativement. Utiliser n’importe quelle autre fonctionnalité de API Platform consiste juste à ajouter quelques lignes de configuration. Découvrez ça dans notre guide de démarrage.

Si vous n’aimez pas les annotations, vous pouvez utiliser les fichiers de configuration au format XML ou YAML à la place. Si vous n’aimez pas l’ORM Doctrine ou si vous ne souhaitez pas utiliser le validateur Symfony, vous pouvez créer des adaptateurs pour brancher votre code personnalisé et utiliser vos bibliothèques préférées. En somme, API Platform a été conçu pour être complètement extensible.

La distribution officielle d’API Platform est fournie avec une configuration Docker adaptée au développement d’API. Cela inclut Apache + PHP7 et une image MySQL. Pour faire fonctionner une application API Platform de manière optimisé sur votre machine, tapez la commande suivante dans son répertoire racine :

Une fois que l’application est démarrée, rendez vous sur http://localhost pour commencer à jouer avec votre API.

Les images API Platform peuvent également être déployées en production facilement en utilisant Docker Swarm (Amazon Web Services, Azure...) ou Google Container Engine (avec Kubernetes).

Au lieu de créer votre propre modèle de données, pourquoi ne pas réutiliser des vocabulaire ouverts comme le très populaire Schema.org et ainsi profiter de la puissance des Linked Data et du web sémantique ? Exactement comme le fait Google, mais grâce à un framework 100% libre.

Depuis sa première sortie, API Platform est fourni avec un générateur de code permettant de générer un modèle de données en PHP incluant les classes, les propriétés, les getters et setters, une PHPDoc complète, les mappings avec l’ORM Doctrine, les annotations de validation et le mapping avec le vocabulaire externe supporté par API Platform. Ce générateur a été mis à jour afin d’être compatible avec la nouvelle configuration d’API Platform 2. Grâce à ce générateur couplé au système de création d’API de API Platform, vous pouvez réaliser une API fonctionnelle sans écrire une seule ligne de PHP :

Découvrez en plus au sujet du générateur dans la documentation et la démo.

API Platform Supporte nativement la négociation de contenu (seulement JSON-LD / Hydra étaient précédemment supportés) ainsi que des formats d’API populaires. Afin de pouvoir extraire ou envoyer des ressources dans un format spécifique, activez-les dans le fichier de configuration :

Cette configuration donne accès à l’ensemble des formats disponible (Symfony 3.2 - actuellement en RC - est requise pour le support du YAML et du CSV). Dès lors vous pouvez préciser le format souhaité à travers l’UI ; en utilisant les entêtes HTTP adéquates, ou en ajoutant le nom du format en extension de n’importe quelle URL de l’API (exemple: https://demo.api-platform.com/books.jsonld). L’ajout et utilisation de formats non supporté par défaut peut être réalisé en écrivant des adaptateurs personnalités.

Découvrez plus de détails au sujet de la négociation de contenu dans API Platform

API Platform 2 génère une documentation extensive au format Swagger 2/OpenAPI. Toute les URLs et types sont automatiquement décrits grâce à notre système d’extraction des métadonnées.

Une interface web construite à partir de Swagger UI est aussi automatiquement mise à disposition. Faites appel à n’importe quelle URL de l’API en utilisant un navigateur web et (grâce à l’en-tête HTTP Accept envoyé par le navigateur) API Platform va afficher la requête envoyée à l’API ainsi que la réponse reçue dans une interface web agreable. Une documentation compréhensible par les humains de l’opération en cours sera également affichée.

Explorez la page d’accueil pour découvrir la documentation de toutes les opérations disponibles, incluant la description de toutes les ressources et propriétés extraites des métadonnées PHP. Utilisez le bac à sable pour jouer avec votre API.

Quelques nouveaux filtres ont été ajoutés en complément des filtres existants de recherche, d’ordre, de tri ou de date :

Ces filtres sont désormais disponibles depuis l’UI et documentés dans les formats Hydra et Swagger. Découvrez comment ajouter des filtres dans votre collection d’API

Les filtres sont désormais implémentés grâce à l’utilisation du tout nouveau système d’extension. Ce système permet de se brancher aux processus de génération des requêtes base de données afin de les modifier. Ce système est particulièrement utile pour implémenter des fonctionnalités de sécurité. Découvrez comment exploiter le mécanisme d’extension pour filtrer le résultat d’un point d’entrée en fonction du rôle de l’utilisateur connecté.
 

Toutes les fonctionnalités d'API Platform 2 suivent les recommandations de sécurité édictée par l’OWASP. Nous avons créé une suite de tests pour nous assurer que toutes ces recommandations soient respectées et documentées. Découvrez comment API Platform 2 sécurise votre API

Nous sommes continuellement en train d’améliorer les performances d’API Platform et des composants Symfony que le framework utilise (comme le Serializer ou le composant PropertyAccess). Cette nouvelle version est plus rapide que la V1 et optimise automatiquement les requêtes SQL  en fonction des groupes de sérialisation. API Platform 2 est également compatible avec PHP PM. En l’utilisant, les temps de réponse de l’API sont divisés par 10.

API Platform est conçu comme un ensemble de composants PHP indépendants : son système de métadonnées, les sérialiseurs JSON-LD, Hydra, Swagger et HAL, les bridges Doctrine et Symfony... Tous ces composants peuvent être utilisés séparément pour créer votre propre API. Pour le moment, la bibliothèque Core doit être téléchargée mais une sous-division du dépôt principal (subtree split) sera disponible pour la version 2.1. Ce split permettra l’installation spécifique d’un composant. Les classes spécifiques peuvent déjà être utilisées séparément de la distribution standard, et sans Symfony.

Nous avons également déplacé le code assez générique de API Platform vers Symfony. Par exemple, le nouveau composant Symfony PropertyInfo a été extrait d’API Platform.  Quelques corrections de bugs et des nouvelles fonctionnalités telles que le support des profondeurs maximales de sérialisation ou encore des formats YAML et CSV au sein du Serializer de Symfony ont été réalisées durant le développement d’API Platform.

L'ORM Doctrine n’a jamais été obligatoire pour utiliser API Platform mais l’ensemble des interfaces permettant d’implémenter un backend de persistance différence  a été repensé et est désormais documenté.

Nous avons considérablement amélioré la qualité de code d’API Platform pour sa V2. API Platform v1 était déjà testé via Behat. Dans la v2, nous avons ajouté des tests unitaires supplémentaires afin de prévenir les bugs et de démontrer que chaque classe respecte les principes SOLID. La couverture du code est désormais de 96%. Notre suite de tests est automatiquement lancée sous Linux (en utilisant Travis) et sous Windows (en utilisant AppVeyor).

Nous avons également utilisé Scrutinizr et SensioLabs Insight afin de détecter les mauvaises pratiques et améliorer la qualité globale du code. API Platform est désormais noté 8.7/10 sur Scrutinizr et a reçu la médaille Platinum (meilleure évaluation, donc) sur Insight. 

La documentation a été améliorée et toutes les nouvelles fonctionnalités sont désormais documentées. Le guide de démarrage a été complètement réécrit. Un nouveau site web construit avec React et Redux a également été développé. Il est notamment doté d’un puissant moteur de recherche fourni par Algolia.

API Platform, c’est plus de 100 contributeurs à travers le monde, une core team composée de Hamza Amrouche , Antoine Bluchet, Samuel ROZE, Teoh Han Hui, Théo FIDRY, Vincent CHALAMON et Kévin Dunglas), des workshops et des conférences données à travers le monde (d’ailleurs, ne loupez pas le workshop API Platform de demain lors de la Symfony Con de Berlin).

API Platform est régulièrement classé dans les dépôts PHP les plus populaires de Github auprès de grands projets tels que Laravel, Symfony et Wordpress. Nous avons d’ailleurs dépassé le millier d’étoiles sur Github début novembre ! Des formations, des prestations de développements, un support commercial ainsi que les workshops sont dispensés dans toute l’Europe par Les-Tilleuls.coop, principal sponsor du framework. 

Merci à toutes les personnes qui ont travaillé sur ces développements, à celles qui ont contribué à la documentation ou qui ont participé à populariser API Platform ! Ce projet ne serait rien sans vous !

La sortie de la V2 d’API Platform n’est que la première étape ! Nous travaillons déjà sur de nouvelles fonctionnalités et certaines sont déjà sur le point d’être mergées dans la branche 2.1 :

Restez à l’écoute des prochaines mises à jour ! Si vous ne l’avez pas encore fait, c’est l’occasion ou jamais de tester API Platform !