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 cadriciel (framework) incluant une refonte complète de la conception, des ajouts de nouvelles fonctionnalités et des corrections de bogues.

API Platform est un framework libre (licence 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 le Web des données (linked data). Il permet de réaliser facilement des applications d’une seule page (single‐page applications) ou dédiées aux mobiles en utilisant des bibliothèques JavaScript telles que React ou AngularJS.

Le sponsor principal d’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 les bénéfices engrangés de manière égalitaire.

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

Sommaire

• • Exposer une API en quelques secondes grâce au nouveau système des configuration et de métadonnées
  • Intégration de Docker
  • Un générateur de modèle de données amélioré
  • La négociation de contenu et le support intégré pour JSON-LD, Hydra, HAL, YAML, CSV et XML
  • Une interface utilisateur pratique et une documentation Swagger 2 automatique
  • De nouveaux filtres
  • Sécurisé par défaut, respectant les recommandations de l’OWASP
  • Amélioration des performances
  • Mise à disposition en tant que composants autonomes, dissociés de Symfony et Doctrine
  • Qualité du code et tests automatisés
  • Réécriture de la documentation et nouveau site Web
  • Une communauté en plein essor
  • Les prochaines étapes

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, etc. ;
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 pris en charge par défaut et la couche d’abstraction fournie par le cadriciel permet d’ajouter facilement le prise en charge d’autres nouveaux formats d’API (JSON API et GraphQL sont actuellement en cours de développement) ;
3. chaque fonctionnalité du cadriciel 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 pris en charge), vous pouvez créer de manière très simple une API hypermédia de qualité 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 aux formats JSON-LD, Swagger et 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 deux 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é d’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 la correspondance objet‐base de données (ORM) de Doctrine ou si vous ne souhaitez pas utiliser le validateur de 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 et PHP 7 et une image de 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 d’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 du Web des données et du Web sémantique ? Exactement comme le fait Google, mais grâce à un cadriciel 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 accesseurs et mutateurs (getters et setters), une PHPDoc complète, les correspondances avec l’ORM Doctrine, les annotations de validation et la correspondance avec le vocabulaire externe pris en charge 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 d’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 version candidate — est requis pour la prise en charge du YAML et du CSV). Dès lors, vous pouvez préciser le format souhaité à travers l’interface utilisateur ; en utilisant les en‐têtes HTTP adéquats, ou en ajoutant le nom du format en extension de n’importe quelle adresse URL de l’API (exemple : https://demo.api-platform.com/books.jsonld). L’ajout et l’utilisation de formats non pris en charge 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 interface utilisateur pratique et une documentation Swagger 2 automatique

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

Une interface Web construite à partir de Swagger UI est aussi automatiquement mise à disposition. Faites appel à n’importe quelle adresse 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 humainement compréhensible de l’opération en cours sera également affichée.

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éta‐donné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’interface utilisateur 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. Il 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 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.

Amélioration des performances

Nous sommes continuellement en train d’améliorer les performances d’API Platform et des composants Symfony que le cadriciel utilise (comme le sérialiseur ou le composant PropertyAccess). Cette nouvelle version est plus rapide que la version 1 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 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éta‐données, les sérialiseurs JSON-LD, Hydra, Swagger et HAL, les ponts vers Doctrine et Symfony, etc. 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. Elle 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 suffisamment générique d’API Platform vers Symfony. Par exemple, le nouveau composant Symfony PropertyInfo a été extrait d’API Platform. Quelques corrections de bogues et des nouvelles fonctionnalités, telle que la prise en charge 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 une infrastructure de persistance différente 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 bogues 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 GNU/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.

Une communauté en plein essor

API Platform, c’est plus de cent contributeurs à travers le monde, une équipe principale composée de Hamza Amrouche , Antoine Bluchet, Samuel Roze, Teoh Han Hui, Théo Fidry, Vincent Chalamon et Kévin Dunglas), des ateliers et des conférences données à travers le monde (d’ailleurs, ne loupez pas l’atelier 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 ateliers sont dispensés dans toute l’Europe par Les-Tilleuls.coop, principal sponsor du cadriciel.

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 version 2 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 intégrées à la branche 2.1 :

• le prise en charge native de MongoDB et de JSON API ;
• 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 !

Aller plus loin

• Site Web d’API Platform (956 clics)
• Le code source sur GitHub (260 clics)
• L’annonce de la sortie de la version 2 (162 clics)
• La SCOP Les-Tilleuls.coop (405 clics)