• 50 heures
  • Difficile

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 29/07/2019

Versionnez votre API

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

 

Votre API est amenée à évoluer avec le temps. Votre mission en tant que concepteur et développeur d'APIs est de ne pas perdre vos utilisateurs. Il s'agit même d'augmenter le taux d'adoption de votre API !

Rien de pire pour un utilisateur d'API, lorsque son application s'appuie dessus, de se retrouver du jour au lendemain, avec une application dans les choux parce que l'API que l'on utilise a été modifiée sans même qu'il ait été prévenu ! :'(

Il est donc de bon ton de prévenir vos utilisateurs que votre API est en train d'évoluer, et surtout, donner la possibilité de ne pas casser la compatibilité. Pour ce faire, il suffit de mettre en place un versionnement de votre API afin d'offrir un moyen pour les utilisateurs de votre API de continuer de profiter des anciennes fonctionnalités et de les prévenir que celles-ci vont devenir obsolètes.

Stratégies de versionnement

Pour différencier l'accès à votre API, il existe différentes manières. Il s'agit d'indiquer le numéro de version et vous pouvez le faire à différents endroits :

Stratégie

Exemple

Dans le nom de domaine

 http://v2.domain.name/api

En préfixe de l'URI

 http://domain.name/api/v2

En query string

 http://domain.name/api?v=v2.0.0

En entête HTTP personnalisée

 X-API-Version: 2.0.0

En entête HTTP  Accept

Accept: application/vnd.app.articles+json; version=2.0.0

Comme vous pouvez le constater, plusieurs possibilités !

Je vais orienter un peu votre choix tout de même : dans la mesure du possible, il est mieux de faire en sorte que votre application n'ait pas d'URL qui change (nom de -sous- domaine, URI ou query string). Nous verrons ensemble que le fait gérer nos numéros de versions en entête est facilité par les librairies que nous utilisons pour la construction de notre API (FOSRestBundle et JMSSerializerBundle).

Je vous conseille donc vivement d'adopter l'une des stratégies permettant de mettre le numéro de version en entête HTTP. ;)

Formalisation de la version en entête HTTP  Accept

L'exemple que je donne pour cette stratégie peut paraître barbare, mais chacun des éléments est explicable. Voici un exemple d'entête pour une requête HTTP formalisée par un utilisateur de votre API : application/vnd.app.articles+json; version=2.0.0

Il s'agit en réalité d'un MIME type (identifiant de format de données sur internet) :

  • vnd.app.articlescorrespond au préfixe "vendor" de votre application (pour une API de gestion d'articles d'OpenClassrooms, cela pourrait êtreopenclassrooms.app.articles  par exemple) ;

  • jsoncorrespond à un type de données que l'utilisateur souhaiterait obtenir (souvenez-vous de ce que nous avons vu à propos de négociation de contenu - content negociation) ;

  • version=2.0.0  correspond à la version de l'API que l'utilisateur souhaite interroger.

Et mon API, qu'est-ce que je dois en faire ?

Il y a tout de même un peu de travail pour que notre API soit prête à faire en sorte que les réponses soient rendues en fonction de la version demandée.

Gestion des ressources - Sérialisation

Il s'agit donc d'indiquer pour les propriétés de la ressource depuis et jusqu'à quelle version celle-ci est disponible. Pour ce faire, rien de plus simple ! Suivez le guide ! :D Nous allons indiquer qu'une nouvelle propriété ($shortDescription) apparaît en version 2.0.0.

Commençons par ajouter le nouveau champ à la ressource Article :

<?php

namespace AppBundle\Entity;

use JMS\Serializer\Annotation as Serializer;

/**
 * …
 */
class Article
{
    // …

    /**
     * @ORM\Column(type="text", nullable=true)
     * @Serializer\Expose
     */
    private $shortDescription;

Il faut mettre à jour la base de données avec la commande suivante :

$ bin/console doctrine:schema:update --force
Mise à jour de la base de données
Mise à jour de la base de données

Essayons d'afficher notre ressource :

Nouvelle propriété ajoutée à la resource Article
Nouvelle propriété ajoutée à la ressource Article

Il faut maintenant indiquer depuis quelle version les champs sont disponibles :

<?php

namespace AppBundle\Entity;

use JMS\Serializer\Annotation as Serializer;

/**
 * …
 */
class Article
{
    // …
    
    /**
     * @ORM\Column(type="string", length=100)
     * @Serializer\Expose
     * @Serializer\Since("1.0")
     *
     * @Assert\NotBlank()
     */
    private $title;

    /**
     * @ORM\Column(type="text")
     * @Serializer\Expose
     * @Serializer\Since("1.0")
     *
     * @Assert\NotBlank()
     */
    private $content;

    /**
     * @ORM\Column(type="text", nullable=true)
     * @Serializer\Expose
     * @Serializer\Since("2.0")
     */
    private $shortDescription;
    
    // …
}

Il nous faut ajouter un peu de configuration au FOSRestBundle. Dans un premier temps, il faut activer le versionnement grâce à l'entête de requête HTTP  Accept  avec la configuration suivante :

# app/config/config.yml

fos_rest:
    #…
    versioning:
        enabled: true
        resolvers:
            media_type: # Accept header
                enabled: true
                regex: '/(v|version)=(?P<version>[0-9\.]+)/'
    # …

Il nous faut ensuite déclarer les versions disponibles grâce au MIME types :

# app/config/config.yml

fos_rest:
    # …
    view:
        mime_types:
            json: ['application/json', 'application/json;version=1.0', 'application/json;version=2.0']
    # …

J'indique que l'application est disponible en version 1.0 et 2.0.

Et voilà ! Testons dès maintenant une requête demandant uniquement les informations disponibles pour la version 1.0 :

Requête HTTP avec entête Accept pour n'obtenir que les champs disponibles dans cette version
Requête HTTP avec entête Accept pour n'obtenir que les champs disponibles dans cette version

Comme nous pouvons le constater, nous ne voyons que les champstitleetcontent, comme nous l'avions indiqué en configuration par annotation dans la ressourceArticle.

Modifions la requête pour demander la version 2.0 :

Obtention de la version 2.0 des informations pour la resource Article
Obtention de la version 2.0 des informations pour la ressource Article

Le champs  short_description  est apparu ! Facile non ? :)

Nous en avons fini avec le versionning. Rendez-vous au prochain chapitre pour découvrir comment communiquer avec d'autres API.

Exemple de certificat de réussite
Exemple de certificat de réussite