Pourquoi utiliser RAML pour designer une API RESTful

Qu’est ce qu’un API

On a souvent tendance à limiter l’API aux applications web, mais ces dernières sont définies et utilisées au sein de presque tous les langages, applications elles supportent même la programmation et le design d’interface pour le hardware.

API signifie “Application programming interface”, littéralement il s’agit d’une boite à outils contenants l’ensemble du matériel nécessaire pour bâtir un logiciel. Il s’agit de l’ensemble des blocs de construction permettant aux développeurs de bâtir un nouveau logiciel sur une base existante, cette base existante de fonctionnalités étant mise à la disposition du développeur via l’API.

Les API sont protéiformes, elles sont mises à disposition par les langages de programmation. Par exemple NodeJS fournit au développeur un ensemble de méthodes et de fonctions pré codées lui permettant de bâtir des programmes sans avoir à réinventer la roue à chaque reprise.

Prenons l’exemple simple d’un programme que nous souhaiterions construire dont l’unique but est d’ouvrir un fichier sur le disque et d’afficher son contenu. Afin d’utiliser l’API de Nodejs nous allons donc regarder sa documentation et chercher l’outil nous permettant d’ouvrir un fichier et de le lire. Nous trouvons la documentation de cette api sur cette page https://nodejs.org/api/fs.html.

Au passage, nous abordons ici un point fondamental, la documentation. Une bonne API est bien documentée afin de permettre au développeur de bâtir avec rapidité.

Les API Web

Nous avons abordé les API fournies par les langages de programmations et les programmes développés à partir de ces derniers mais ce qui va surtout nous intéresser dans cet article ce sont les API Web RESTful.

Une API web est là aussi un ensemble de ressources mis à la disposition des développeurs par d’autres développeurs d’application.

Dans la plupart des cas ou nous faisons usage des API Web il s’agit en effet de récupérer de la données d’autres applications. Par exemple nous pouvons utiliser l’API de Twitter pour récupérer l’ensemble des tweets d’un utilisateur. La récupération de données est usage mais pas le seul des API Web, Twitter ainsi mets à la disposition des développeurs des API d’authentification leur permettant de laisser gérer par Twitter l’authentification de leur site par Twitter ! C’est aussi le cas de Facebook par exemple avec le Facebook login button.

La tendance est grande et stratégiquement intéressantes pour les entreprises de mettre à la disposition leurs données à d’autres entreprises afin que ces dernières créent de la valeur par leur biais. Valeur qui est ensuite récupéré soit directement par un paiement à l’appel (au call) ou indirectement par la croissance de données récupérées sur l’utilisateur final…

REST

Derrière cette notion d’API Web on rajoute souvent le mot RESTful. Ce dernier terrorise pas mal de développeurs car il sous entend de nombreuses contraintes dans le développement d’une API. Au passage REST signifie (REpresentational State Transfer).

REST est un style architectural pensé dans les années 60 par Roy Fielding dans sa thése de doctorat (plus précisément chapitre 5 :)
(Pour les curieux voici une traduction française : http://opikanoba.org/tr/fielding/rest/).

Il va donc s’agir pour le créateur de l’API (vous par exemple) de suivre scrupuleusement les principes architecturaux de Roy afin de pouvoir vous vanter d’avoir bâti une API RESTful. Ces principes étant forgés pour une bonne raison, elles assurent que votre API se comportera de manière identique pour 5 utilisateurs comme pour 5 millions (notion de scalabilité). Elle assurera aussi que votre API sera compréhensible par tous le monde car tous le monde utilise le même modèle, (pas forcément le même langage de programmation mais du moins le même mode de fonctionnement)

Nous allons passer brièvement sur les contraintes (qui feront surement l’objet d’un autre article de ma part afin de creuser un peu plus le sujet)

Des contraintes architecturales pensées pour notre bien…

Une API RESTFul: :

1. Est sans états (Stateless) : lorsque vous appelez l’API a plusieurs reprises et vous faites la même demande l’API ne se souviendra pas de vos demandes précédentes car elle n’a pas de mémoire. On ne stocke pas d’informations entre les requêtes. Cette contraintes est directement lié au protocole HTTP qui lui même ne conserve pas d’états.

2. A la possibilité de mettre en “cache” certaines informations. Par exemple imaginons qu’un nombre important de développeur utilise l’API Open Graph de Facebook pour retrouver le profil de Zuck. On peut parier que cette requête est faite de nombreuses reprises. Facebook (le producteur de l’API) va sans aucun doute mettre en mémoire la réponse à cette requête afin d’économiser le temps de recherche dans ces bases de données. La seule contrainte imposée au développeur RESTful est de préciser à l’utilisateur que l’information est en cache. (Afin de ne pas afficher à nos propres utilisateurs des informations non à jour, si jamais Zuck décide de divorcer par exemple)

3. Doit et peut avoir un système composé de serveurs multiples ou l’information est répliqué. Facebook par exemple n’a pas qu’un seul serveur, mais dispose d’une armada de machines qui peuvent répondre à la même requête. Cette caractéristique couplée à la première permet d’avoir un système qui va monter en charge sans embûche, car si il y a un pic de demande on peut rajouter des serveurs à la volée dans le système.

4. Une interface uniforme : cette contrainte est un peu plus difficile à comprendre car elle regroupe elle même 4 contraintes. Ce qu’il est important de retenir est que chaque ressource (données mise à disposition : par exemple le profil Facebook, la liste d’amis, la liste des likes…) est correctement identifiée dans les call que l’on va faire à l’API. Je zappe volontairement la contrainte de manipulation des ressources via leur représentation ainsi que la contrainte HATEOAS, traité dans un prochain article. Vient ensuite la notion des messages de retour de l’API. Ces derniers doivent être auto-descriptifs, c’est à dire que le développeur doit comprendre immédiatement ce que l’API revoit. Par exemple en cas d’erreur le développeur doit prévenir le client de son API de la cause de cette dernière.

   Bâtir une API RESTful

   Tout cela est bel et bon, mais comment donc bâtir avec ces contraintes ? Le défi est important si l’on ne part pas d’une base. Eh bien figurez vous que vous n’êtes pas seul à avoir embrassé la difficulté du REST car des Frameworks existent et permettent de démarrer très rapidement sans avoir à trop transpirer sur vos claviers.

   Le sauveur est nommé RAML. RAML (RESTful API Modeling Language) est un langage vous permettant de désigné une API très rapidement respectant les principes architecturaux de REST. RAML permet de respecter les contraintes tout en étant très facile à lire (il repose sur le langage YAML, format de présentation de données très facile à lire développé par Clark Evans en 2001).

   Sa facilité de lecture lui permet d’être compréhensible par l’ensemble de la communauté des développeurs. En fait une API grâce à RAML est définit dans un simple fichier. Dans ce dernier on peut voir immédiatement ce que cette dernière fait. Procédé ainsi permet d’avoir un système maintenable sur le long terme.

   Unfortunately, people are fairly good at short-term design, and usually awful at long-term design (Roy Fielding)

RAML permet d’avoir une rédaction de spécification claire précise efficace et maintenable sur le long terme même si les équipes évoluent. Il est fini le temps ou un seul élément détient le savoir sur le fonctionnement d’une machine.

En guise d’introduction voici un exemple de fichier RAMML définissant une API simple :

#%RAML 0.8
---
title: Facebook API
baseUri: http://api.fbbbb.com/{version}
version: v1

/users:
  /{username}
    get:
      queryParameters:
        first_name:
          displayName: First Name
          type: string
          description: The First Name of an user
          example: Joe
          required: false
        last_name:
          displayName: Last Name
          type: string
          description: The Lasr Name of an user
          example: Doe
          required: false
    put:
      queryParameters:
        access_token:
          displayName: Access Token
          type: string
          description: Token giving you permission t put info
          required: true

Ce fichier RAML définit une API imaginaire de Facebook (qui existe bel et bien) permettant de retrouver des informations sur un utilisateur en particulier (son prenom et nom).

Par exemple pour recevoir les informations concernant l’utilisateur “jonhdoe75” nous allons juste devoir faire un call sur l’URL suivant :

http://api.fbbbb.com/v1/users/jonhdoe75

La seconde étape consiste à construire l’ensemble de la logic derrière cahque call. Cela peut être fait grâce à Sosprey avec NodeJS (http://www.raml.org/blogs/osprey-out).

Voici un article à lire pour finir :

• https://github.com/raml-org/raml-tutorial/blob/master/tutorial.md
  Il s’agit d’un bon tutorial pour commencer à écrire vos premiers fichiers RAML.