API Platform 2 : un cadriciel pour créer des API Web hypermédia en quelques minutes

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 vient d’être publiée. 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.

API Platform est un framework libre (license MIT) écrit en PHP 7 et basé sur Symfony destiné à la création d’API web modernes, puissantes et sécurisées. Cet outil est particulièrement adapté à la construction de systèmes d’informations API-centric basés sur l’hypermédia et les Linked Data. Il permet de réaliser facilement des Single-Page Applications (en utilisant des bibliothèques JavaScript telles que React ou Angular) et des applications mobiles.

Le sponsor principal de API Platform est la société coopérative lilloise Les-Tilleuls.coop. Il s’agit d’une SCOP spécialisée dans la conception et la réalisation de logiciels comptant une vingtaine de salariés qui pratiquent l’autogestion et se partagent égalitairement les bénéfices engrangés.

Capture d'écran

En seconde partie de la dépêche, vous trouverez une traduction en français de l’annonce de sortie de cette version deux, qui revient sur les fonctionnalités principales du framework.

Sommaire

API Platform repose sur trois principes fondateurs :

  1. créer une API facilement et rapidement : n’importe quel développeur web doit pouvoir créer une API REST et obtenir le support du CRUD, une documentation auto-générée, l’authentification via JSON Web Token ou OAuth, la gestion des en-têtes CORS, la validation des données, les tris et les filtres, le cache…
  2. les formats ouverts modernes sont gérés nativement, sans demander de travail supplémentaire pour le développeur : Swagger/OpenAPI, JSON-LD, Hydra, HAL, API Problem (RFC 7807), Schema.org sont supportés par défaut et la couche d’abstraction fournie par le framework permet d’ajouter facilement le support d’autres nouveaux formats d’API (JSONAPI et GraphQL sont actuellement en cours de développement) ;
  3. chaque fonctionnalité du framework doit être extensible, modulaire et débrayable.

Exposer une API en quelques secondes grâce au nouveau système des configuration et de métadonnées

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 hypermédia de qualité simplement en modélisant vos données sous forme de classes PHP et en ajoutant quelques annotations.

Exemple :

<?php

// src/AppBundle/Entity/Book.php

namespace AppBundle\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * A book.
 *
 * @ApiResource
 * @ORM\Entity
 */
class Book
{
    /**
     * @var int The id of this book.
     *
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    public $id;

    /**
     * @var string|null The ISBN number of this book (or null if it doesn't have one).
     *
     * @ORM\Column(nullable=true)
     * @Assert\Isbn
     */
    public $isbn;

    /**
     * @var string The title of this book.
     *
     * @ORM\Column
     * @Assert\NotBlank
     */
    public $title;

    // Prefer private properties, accessors and mutators in real applications
}

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

  • des opérations CRUD ;
  • la validation des données et la sérialisation des erreurs Les formats JSON-LD, Swagger, Hydra ;
  • la pagination ;
  • une interface utilisateur agréable et une documentation autogénérée utilisant les données de la PHPDoc.

Consultez la 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 le 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.

Intégration de Docker

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ée sur votre machine, tapez les commandes suivantes dans son répertoire racine :

$ docker-compose up -d # Télécharge, construit et exécute les images Docker
$ docker-compose exec web bin/console doctrine:schema:create # Crée le schéma MySQL, nécessaire une seule fois

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).

Un générateur de modèle de données amélioré

Au lieu de créer votre propre modèle de données, pourquoi ne pas réutiliser des vocabulaires 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 créer 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 :

types:
    Book:
        parent: false # Generate only one class, not the full hierarchy from Schema.org
        properties:
            isbn: ~
            name: ~
            description: ~
            author: { range: Text }
            dateCreated: ~
    Review:
        parent: false
        properties:
            reviewBody: ~
            rating: { range: Integer, nullable: false } # This is a custom field that doesn't exist in the vocab
            itemReviewed: { range: Book, nullable: false, cardinality: '(*..1)' }

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

La négociation de contenu et le support intégré pour JSON-LD, Hydra, HAL, YAML, CSV et XML

# app/config/config.yml

api_platform:
    formats:
        jsonld:  ['application/ld+json']
        jsonhal: ['application/hal+json']
        xml:     ['application/xml', 'text/xml']
        json:    ['application/json']
        yaml:    ['application/x-yaml']
        csv:     ['text/csv']
        html:    ['text/html'] # This is the API Platform UI

Cette configuration donne accès à l’ensemble des formats disponibles (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és par défaut peuvent être réalisés en écrivant des adaptateurs personnalisés.

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

Une “UI” pratique et une documentation Swagger deux automatique

API Platform deux génère une documentation extensive au format Swagger deux/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 agréable. Une documentation compréhensible par les humains de l’opération en cours sera également affichée.

Doc

Explorez la page d’accueil de votre API 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.

De nouveaux filtres

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

  • le filtre booléen permettant de filtrer les propriétés booléennes ;
  • le filtre numérique permettant de filtrer les champs numériques.

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é.

Sécurisé par défaut, respectant les recommandations de l’OWASP

Toutes les fonctionnalités d’API Platform deux 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 deux sécurise votre API.

Amélioration des performances

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 version un et optimise automatiquement les requêtes SQL en fonction des groupes de sérialisation. API Platform deux est également compatible avec PHP PM. En l’utilisant, les temps de réponse de l’API sont divisés par dix.

Mise à disposition en tant que composants autonomes, dissociés de Symfony et Doctrine

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é.

Qualité du code et tests automatisés

Nous avons considérablement amélioré la qualité de code d’API Platform pour sa version deux. API Platform v1 était déjà testé via Behat. Dans la version deux, 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.

Réécriture de la documentation et nouveau site web

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.

Doc

Une communauté en pleine essor

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 !

Les prochaines étapes

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 :

  • le support natif de MongoDB et le support de JSONAPI ;
  • une auto génération de l’administration via l’utilisation de React et Admin On Rest.

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 !

Si vous aimez le projet, vous pouvez nous aider en nous donnant une étoile sur GitHub !

Lire les commentaires

(Source: LinuxFr.org : les dépêches)
Logo