Faciliter la consommation d'API avec Jane

Au sein de JoliCode, Jane fait partie de la boîte à outils que nous utilisons lorsque nous développons des APIs. Cet article vise à vous faire un retour d'expérience sur son utilisation chez l'un de nos clients.

Qu'est-ce que Jane ?

La librairie Jane est un projet entièrement open-source qui va vous permettre de simplifier l'utilisation de vos APIs. Elle va vous permettre de générer un client d'API, les "(de)normalizers" et les modèles de votre API en se basant sur votre description d'API (OpenAPI/Swagger).

• Si vous disposez déjà d'un schéma OpenAPI, vous pouvez utiliser Jane.
• Si vous développez une API et que vous n'avez pas de schéma OpenAPI, vous pouvez en créer un rapidement via le SwaggerEditor puis utiliser Jane.

Il existe bien sûr d'autres générateurs de client d'API basés sur OpenAPI.

OpenAPI.tools en recense de nombreux dans différentes technologies. L'intérêt de Jane est qu'il est écrit en PHP et s'intègre très bien dans l'écosystème Symfony (il s'appuie notamment sur le Serializer de Symfony).

Enfin, pour être complet, le développement de Jane est sponsorisé par JoliCode.

Mes collègues ont déjà parlé de cet outil à plusieurs reprises :

• Etat de l’art d’Elasticsearch avec PHP
• Jane 5.0 has been released
• Lightning talk de Baptiste Leduc au Forum PHP 2019

Contexte client

Dans le cadre de nos missions d'expertises techniques, nous maintenons quelques APIs chez ARTE dont l'API "OPA" qui met à disposition l'ensemble des métadonnées des programmes diffusés par la chaîne.

Cette API est consommée par plusieurs clients dont deux autres API écrites en PHP (Symfony) :

• "Player" qui permet de générer les données qui seront consommées par les players vidéos (web, mobile, tv) ;
• "Feed" qui permet de générer des flux (XML, JSON) pour les différents partenaires (box Internet, over-the-top, ...).

Au départ, nous avions mis à disposition une spécification OpenAPI v2 (Swagger) afin de pouvoir rendre disponible une sandbox de l'API (Merci NelmioApiDocBundle, SwaggerEditor). Dans un second temps, nous nous sommes rendus compte que le travail qui avait été fait pour bien spécifier les réponses des endpoints pouvait être utilisé pour faciliter le développement des clients des APIs "Player" et "Feed".

C'est ici que Jane intervient. À partir de la spécification OpenAPI, nous avons pu générer un kit de développement (SDK) / client pour plus facilement interagir avec OPA. Ce kit de développement dispose de son propre dépôt github et de son fichier composer.json afin de faciliter son intégration à un projet existant :

{
"name": "arte/api-opa-php-sdk",
"description": "A PHP client for OPA API",
"type": "library",
"license": "MIT",
"autoload": {
    "psr-4": {
        "Arte\\OPA\\Api\\": "generated/",
        "Arte\\OPA\\": "src/"
    }
},
"require": {
    "php": ">= 7.1",
    "jane-php/open-api-runtime": "^4.0",
    "php-http/client-common": "^1.7 || ^2.0"
},
"require-dev": {
    "jane-php/open-api": "^4.0",
    "php-http/curl-client": "^1.7 || ^2.0",
    "guzzlehttp/psr7": "^1.4",
    "friendsofphp/php-cs-fixer": "^2.13"
    }
}

Ce projet dispose de son propre Makefile afin de faciliter la mise à jour des fichiers générés. Lorsqu'une nouvelle version de l'API OPA sort, nous re-générons le SDK et créons une nouvelle version avec make generate :

generate: ## Update client based upon OpenAPI specifications
    rm -rf generated && php vendor/bin/jane-openapi generate

Le fait de disposer d’un projet github dédié nous permet de sauvegarder la configuration Jane du projet :

<?php

return [
    'openapi-file' => __DIR__ . '/opa-openapi-v2.json',
    'namespace' => 'Arte\OPA\Api',
    'directory' => __DIR__ . '/generated',
    'reference' => true,
    'strict' => false,
    'use-cacheable-supports-method' => true,
];

Dans les projets qui dépendent du SDK, nous avons simplement à ajouter une dépendance au SDK :

"require": {
    ...
    "arte/api-opa-php-sdk": "^1.1",
    ...

Nous pouvons ensuite facilement manipuler les réponses et objets fournis par OPA. Le SDK est hébergé sur un dépôt privé mais si vous souhaitez voir du code, je vous invite à consulter l'exemple mis à disposition par Jane.

Bénéfices

L'utilisation du SDK a de nombreux bénéfices :

• Cela nous force à être rigoureux et à bien spécifier les différents modèles au niveau de l'API. Une erreur dans la spécification OpenAPI aura des conséquences sur le code généré par Jane et pourra créer des problèmes dans les projets consommateurs de l'API ;
• Dans les projets consommateurs (ici "Player" et "Feed"), nous manipulons directement des objets PHP tels qu'ils ont été décrits dans la spécification OpenAPI. C'est très confortable et nous permet de nous focaliser sur le développement de règles métiers. Nous n'avons pas à nous soucier de la manière dont les réponses des API doivent être traitées (C'est Jane qui s'est occupé d'écrire les "denormalizers"). On ne manipule plus des tableaux ou des \stdClass. À noter que Jane écrit ses propres denormalizers (exemple ici au contraire du ObjectNormalizer de Symfony qui utilise la Reflection pour extraire les attributs à dénormalizer. Cela rend la dénormalisation bien plus performante. Jane prévoit à moyen terme d’utiliser un automapper afin d’améliorer encore un peu plus les choses.

Inconvénients

Bien sûr, il y a quelques inconvénients à utiliser Jane :

• perte de la maîtrise sur la désérialisation des réponses mais nous avons confiance dans les équipes qui maintiennent l'outil pour proposer quelques choses de chouette
• des soucis de performance. Pour des objets simples, Jane ajoute un léger overhead puisqu’on passe par des dénormalizers.

Il y a sûrement d'autres inconvénients mais les bénéfices sont tellements plus importants que nous ne nous voyons pas ne plus utiliser Jane.

Si vous aussi, vous consommez des API complexes, sautez le pas et testez Jane, vous ne serez pas déçus.

Excellentes fêtes de fin d’année.