Les web services REST, Pourquoi ? Comment ?

Michael Bailly Architecture , , ,

L’interconnexion et la communication entre différents systèmes informatiques est un sujet certainement aussi ancien que l’informatique en réseau elle-même.
Il s’agit ici d’assurer la consommation et la mise à jour des données… vaste sujet !

Une des premières approches a été d’utiliser la base de données comme point central des systèmes : plusieurs applications se connectent sur la BDD et réalisent des opérations « CRUD ».

Cette approche, simple et efficace  soulève deux problèmes majeurs :

  • Le premier est que la base de données devient l’élément central de l’architecture; c’est le « SPOF » du système et il est toujours compliqué d’optimiser les requêtes – celle ci devant être réalisée sur l’ensemble des applications qui s’y connectent.
  • Le second problème est que, en cas d’évolution du modèle de données, l’ensemble des applications doivent être adaptées pour réaliser des requêtes valides. Une difficulté majeure qui en découle est que ces adaptations doivent être déployées dans la plupart du temps pour toutes les applications de façon simultanée, dans le cadre d’une opération Big-Bang (mise à jour de la BDD puis de l’ensemble des applications qui l’utilisent), ou bien par la mise en oeuvre d’un plan de migration complexe.

Une autre approche classique consiste à mettre en oeuvre des systèmes d’imports/exports par traitements batchs couplés la plupart du temps à des ETL. L’inconvénient ici, au dela du faite que les données sont dupliquées, réside à devoir prendre en compte que les informations ne sont pas actualisées en temps réel. En général les traitement batchs sont nocturnes et les systèmes travaillent sur des données « non-fraiches ».

Partant de cette problématique, s’est dessiné le besoin de rajouter une couche intermédiaire d’accès aux données dans le dispositif de communication entre systèmes. Des architectures type SOA ont petit à petit vu le jour dans les systèmes d’informations : le SI est ici considéré comme un agrégat de services, qui sont interconnecté entre eux. L’implémentation la plus couramment rencontrée dans ce type d’architectures est SOAP, dont les concepts sont d’exposer des traitements sur le réseau, au moyen du protocole HTTP, en utilisant le langage XML.

De façon identique à cette évolution dans les SI traditionnels d’entreprise, le web (HTTP), devient le standard de-facto pour l’exposition de données, tandis que les clients (navigateurs, applications mobiles) deviennent de plus en plus puissants avec l’évolution et la disponibilité de devices de plus en plus puissants et ergonomiques. Du coup, les architectures SI/Web exposent de plus en plus directement les données aux « clients », qui prennent en charge seuls les opérations de mise en forme sur les écrans. Dans ce contexte « web », le protocole SOAP n’est pas optimal : le format XML est lourd à parser sur un navigateur (problématique de performances/temps de traitements) et la couche de transport HTTP n’est pas utilisée à son plein potentiel. Pour exemple : un service SOAP renvoie toujours un code HTTP 200 (OK), et après analyse du XML que l’on sait si le traitement est en erreur. Les développeurs doivent donc mettre en place une gestion des erreurs multiples: au niveau du protocole de transport, puis au niveau du protocole SOAP.

Ainsi,de manière naturelle, et organique comme bien souvent sur Internet, les applications se mettent de plus en plus à exposer leurs données au format JSON, qui est un format natif en JavaScript, bien moins verbeux, transformable immédiatement en objet informatique. L’intérêt pour REST, un terme décrit par Roy Fielding en 2000, connaît un intérêt croissant depuis 15 ans, avec une accélération sensible depuis 2011 (https://www.google.fr/trends/explore#cmpt=q&q=/m/03nsxd&cat=0-5).

REST (pour REpresentational State Transfer) ne décrit pas une implémentation mais un style d’architecture qui suit différents principes :

  • 1/ client-serveur: les responsabilités sont séparées entre le client et le serveur. L’interface utilisateur est séparée de celle du stockage des données. Cela permet aux deux d’évoluer indépendamment (contrairement à des applications qui réalisent des requêtes directement en base de données par exemple…).
  • 2/ sans état: la requète envoyée par le client doit être auto-suffisante : ne pas nécessiter de sauvegarder un état sur le serveur
  • 3/ mise en cache : la possibilité pour le serveur de spécifier les réponses pouvant être mises en cache
  • 4/ une interface uniforme : chaque ressource est identifiée unitairement, les ressources ont des représentations définies
  • 5/ un système hiérarchisé par couche: les états de l’application sont représentés par des ressources individuelles. L’ensemble de l’information n’est pas envoyée dans une ressource unique.

À noter qu’on assimile « API REST » avec l’application de ce style d’architecture sur le protocole HTTP et en utilisant le format d’échange de données JSON.

Quels avantages trouve-ton dans l’utilisation d’API REST ?

  • Un protocole REST permet d’être simplement accédé, aussi bien par un autre élément du SI, que par une application cliente. On parle alors d’architecture WOA (Web Oriented Architecture), qui est un sous-ensemble des SOA. il n’y a pas de « préjugé » côté client.
  • Avec son approche orientée ressources (au lieu de traitement), et le fait que les serveurs sont sans état, la tenue de la charge est facilitée par la possibilité de passer à l’échelle une partie du SI qui serait particulièrement sollicitée.
  • Le protocole HTTP est un protocole déconnecté, extrêmement maîtrisé par tous les devops, sys admin, developpeurs…. Les outils de protection (firewalls), de tenue de la qualité de service, ainsi que les librairies de développement d’API existent et sont omniprésents dans de nombreux environnements: la plupart des organisations utilisent aujourd’hui ces API REST pour permettre l’accès aux données de leurs différents systèmes.

Une généralisation de l’Utilisation du REST et la naissance de la mouvance « OPEN API »

Dans la mouvance dite « Open API » ou encore écosystème ouvert (https://www.octo.com/publications/11-les-geants-du-web/), de nombreuses organisations partout dans le monde entier ont mis en place des services REST permettant de consulter, et parfois mettre à jour, les données. Par exemple,

  • En France, les données de la plupart des ministères sont regroupées sur un site. Les données sont accessibles via un protocole REST (https://www.data.gouv.fr/fr/ , https://www.data.gouv.fr/fr/apidoc/).
  • de nombreuses sociétés « privées » ou semi privées proposent également la mise à disposition de données via API REST : la SNCF (data.sncf.com/api) pour les données de traffic et les itinéraires, JC Decaux (https://developer.jcdecaux.com/#/home) pour la disponibilité des vélos (velib) en temps reel, la RATP, …

Cette généralisation du « REST » est rendue possible par différents outils, et l’étendue des produits et contributions Open Source qui permettent de mettre en oeuvre ces architectures est aujourd’hui « infinie ». Par exemple,

Dans la pratique… quelques considérations concernant les principes et les outils open source

Les API REST exposées par une entreprise évoluent en permanence pour répondre toujours mieux aux besoins des utilisateurs, clients, partenaires, collaborateurs mais il n’est pas réaliste & raisonnable de demander aux systèmes d’informations qui les consomment de suivre les évolutions de ces APis sur un rythme imposé par le producteur de services. Ainsi, Il est important d’assurer une manière pour les développeurs d’API de fournir de nouvelles versions de celles-ci, tout en proposant aux consommateurs de choisir la version sur laquelle ils vont construire leurs applications, avec une garantie de pérennité dans le temps….:  Le succès de l’utilisation des API repose sur la facilité de leur utilisation et la garantie de leur durée dans le temps. Lorsqu’on met à disposition une API, le « client » à séduire est le développeur de l’application qui viendra consommer ces API ! Du coup les API doivent être utiles et simples à comprendre, très bien documentées, et doivent être pérennes dans le temps.

Concernant la documentation, Il existe deux outils communément répandus pour documenter des API :

  • Swagger (http://swagger.io/) est certainement le système le plus utilisé pour générer une documentation d’API REST. C’est un produit sous licence Apache composé de plusieurs éléments : une spécification (nommé OpenAPI http://swagger.io/specification/ ) qui permet de décrire au format JSON une API REST / un module « CORE » qui s’appuie sur la norme Java « JAX-RS » qui génère automatiquement le fichier JSON de description de l’API REST. L’écosystème Swagger intègre aussi une constellation d’utilitaires : codegen ( outil en ligne de commande permettant de générer un client et un serveur à partir d’un fichier de définition OpenAPI, Editor  (un éditeur web pour lire les fichiers OpenAPI), UI ( interface web pour explorer une API REST définie avec la norme OpenAPI), Swagger-js (un client JavaScript pour requèter des API REST), Swagger-node (librairies pour aider à la création d’un serveur REST à partir de fichier OpenAPI), Swagger-socket (interface d’API OpenAPI sur le transport WebSocket)…..etc.
  • Apidoc (http://apidocjs.com/) lit les commentaires de code et en crée une documentation. Apidoc est donc complètement indépendant du langage utilisé pour implémenter le service REST. Bien entendu, les commentaires dans le code doivent contenir des identifiants spécifiques pour décrire l’API.

Concernant le cycle de vie des APIs, Il existe trois stratégies de versioning de l’API :

  • Spécification de la version d’API dans l’URI
    Exemple : GET /api/v2/users/aeb234c4
    Les arguments en faveur de cette méthode sont qu’elle est très visuelle et qu’elle permet une communication extrêmement facile (envoi par email du lien par exemple). Elle ne correspond cependant pas au dogme REST, qui dit qu’une ressource et son URL ont une correspondance unique.
  • Spécification de la version d’API dans un entête dédié
    Exemple : GET /api/users/aec234c4  Api-Version : 2
    Les arguments en faveur de cette méthode sont qu’elle reste assez explicite, qu’elle est simple à programmer au niveau du client d’API. La sémantique n’est cependant pas particulièrement bonne ; en effet HTTP propose déjà le header Accept pour ce type de négociation.
  • Spécification de la version d’API en utilisant le header Accept
    Exemple : GET /api/users/aec234c4 Accept: application/vnd.myapplication.v2+json
    Les arguments en faveur de cette méthode sont qu’elle semble la plus fidèle à « l’esprit » REST, elle est cependant compliquée à programmer pour le client… et dans une moindre mesure pour le serveur et est moins lisible que les deux autres.Le choix de l’une des méthodes sera fortement lié à la culture d’entreprise et aux objectifs sous-jacents de la création de l’API. Pour autant on peut souligner les éléments suivants :

    • l’indication du numéro de version dans l’URL semble être la manière la plus simple de spécifier, et c’est la seule manière qui permet d’envoyer les API par lien (email, tweets, …) et c’est probablement pour cela que la quasi totalité des grands fournisseurs publics d’API utilisent cette méthode ( http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/ )

    • Cette méthode est pour autant la moins valide des méthodes pour les puristes de l’architecture RESTFull. Pour ces derniers le header Accept : semble être la plus acceptable des solutions

    • Ces solutions ne sont pas exclusives : votre serveur peut tout à fait supporter l’indication de version de l’API et dans l’URL, et dans un header api-version, et dans le header Accept.

Concernant le scafolding, Il existe peu de logiciels permettant d’exposer directement des tables SQL sous forme d’API REST. Les deux principaux logiciels Open Source sont :

Dream Factory  ( Editeur : Dream Factory Inc. (US) / Licence : Apache 2)
https://github.com/dreamfactorysoftware/dreamfactory/
https://www.dreamfactory.com
Cette solution est très complète et inclut en outre des drivers pour pouvoir présenter des API REST à partir de bases NoSQL et de systèmes de stockage de fichiers. L’interface de management web est ultra complète, des scripts de traitement peuvent y être raccrochés  à différentes étapes de la requète REST (par exemple pour de la validation de champs, ou la gestion d’un workflow), un système de gestions d’autorisations basé sur RBAC y est disponible. Dream Factory est utilisée par un nombre important d’entreprises (ex Salesforce, Xerox).

Database to API (Editeur : Project Open Data / Licence : GPLv3 et +)
https://github.com/project-open-data/db-to-api
https://project-open-data.cio.gov/
Langage : PHP
Le Gouvernement américain met à disposition, en Open Source, un ensemble de contributions permettant de faciliter la mise à disposition d’API en OpenData. Database to Api n’est pas une solution clé en main, il s’agit plus d’un socle, dont l’appropriation est simple, et qui peut évoluer pour s’adapter aux besoins métier.

Concernant la programmation des APIs, Il existe deux différences principales entre des interfaces type Soap et des approches RestFull. La première est que Soap expose des traitements, alors que REST expose des ressources. La seconde est que les webservices type Soap possèdent un standard de description des traitements et structures du web service (WSDL), tandis que les API REST n’en disposent pas. Plusieurs approches sont apparues dans l’univers REST pour « pallier » à ce sujet de description des APIs.

  • WADL (Web Application Description Language, https://www.w3.org/Submission/wadl/) est la transposition de la norme WSDL, mais pour les interfaces type REST.  Cette norme utilise XML comme format de description. Son adoption n’est pas très forte.
  • Open API (https://openapis.org/) est un consortium créé par Swagger et un bon nombre de géants du web (IBM, Atlassian, Google, Microsoft, Paypal entre autres). Il est écrit au format YAML.‘Le point intéressant dans cette norme est qu’elle est liée à l’ensemble d’outils Swagger, ce qui permet d’auto générer et d’entretenir simplement ce fichier de description. Elle est la plus adoptée.
  • HATEOAS (Hypermedia as the Engine of Application State) prend une voie différente : il propose de rajouter une contrainte à l’architecture REST. La contrainte est d’ajouter dans chacune des entités REST retournée, des liens qui permettent de découvrir les actions possibles à réaliser à partir de la ressource. Ce concept fait partie de REST tel que son « inventeur » Roy T. Fielding l’a pensé (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven). Le parti pris est de rajouter dans la description de la ressource un objet _links qui contient les liens en rapport avec la ressource actuelle. Dans le cas d’une liste de ressources, cela peut être « la page suivante », « la recherche sur ce type de ressource ». Pour une ressource précise, l’information peut être contextuelle. Cette approche est de plus en plus reconnue des concepteurs d’API, parce qu’elle permet au logiciel client de découvrir petit à petit les API possibles à partir de l’API requêtée, et parce que ces liens peuvent évoluer, en fonction d’un contexte. HAL est l’implémentation en JSON du format HATEOAS.
  • Un autre format hypermédia utilisé fréquemment est JSON-LD. Il utilise lui aussi des noms de propriété dédiés pour rajouter des informations contextuelles dans les objets ressource.
  • Collection+JSON : Ce format, relativement nouveau (2012), prend en compte les collections autant que les ressources elles-même. Il supporte les liens, la description de paramètres de endpoint ainsi que la notion de requêtes de recherche.

Sur ces sujets, une bonne pratique est de disposer d’une documentation à destination du développeur, et Swagger (OpenAPI) permet cela, en plus d’offrir un fichier descriptif des API REST de l’application. L’ajout d’un système hypermédia à l’intérieur même de la ressource métier est un travail de plus grande ampleur. Les fonctionnalités additionnelles offertes pourront être sous-exploitées au lancement de l’API ; c’est un choix qui peut s’avérer payant sur le long terme. Dans ce cas, HATEOAS ou JSON-LD+Hydra sont les meilleures options.

Dans la pratique… quelques considérations concernant les architectures REST

Une option gagnante pour la souplesse d’administration du SI, sa scallabilité, sa souplesse…. est de diviser les responsabilités des applications dans de petites API isolées. Ce principe d’architecture s’articule ainsi autour des concepts des « micro-services » qui sont aujourd’hui largement plebiscités : en c ompar aison à une grosse application monolithique, il est possible de réduire la quantité de tests à effectuer lorsqu’on a corrigé un bug, de choisir des librairies et langages de programmation différents en fonction des , et surtout de pouvoir adapt er son système pour répondre mieux aux besoins de tenue en charge, à l’étendue des fonctionnalités à mettre en place et également à la disponibilité attendue pour les applications.Il faut aussi garder en tête que le nombre d’API du système va augmenter au fil du temps et dans le cas où elles sont exposée s vers l’extérieur, le partitionnement permet d’appliquer des règles plus ciblées sur la restriction d’accès.

Exposer ses données au travers d’une ou plusieurs APIs, n’implique pas forcément une architecture spécifique. Cependant il existe grossièrement deux façons d’architecturer ses APIs et les composants complémentaires, permettant de répondre aux besoins courants d’un fournisseur de service :

1/ En assemblant des outils : Différents outils et librairies sont utilisés dans le code de l’API elle-même, pour gérer les aspects de sécurité, d’analytique, etc. Un frontal HTTP type apache ou nginx, doit être mis en place pour aiguiller les requêtes vers l’API demandée et pour répartir la charge. La supervision doit également être assurée par un service tiers. Les avantages ici sont

  • que chaque API définie son comportement, elle peut par exemple choisir de faire de l’authentification ou non, avoir ses règles d’autorisation, émettre des informations d’utilisations basées sur des règles métiers
  • que les éléments ont leur propre cycle de vie (mise à jour, sauvegarde, …)
  • Qu’il est possible de choisir un outil spécifique pour chaque besoin, et le remplacer si nécessaire

Quelques inconvénients cependant

  • Chaque API doit être développée de manière très complète, le même travail est fait plusieurs fois alors que les besoins sont souvent les mêmes entre les APIs

  • Plus d’outils doivent être mis en œuvre et maîtrisés par les administrateurs

  • Les outils ne sont pas uniformes

  • L’architecture peut être complexe à concevoir et à maintenir

2/ En utilisant une passerelle : Pour cette architecture, une passerelle est mise en façade du système d’API. Comme le ferait un frontal web, ce service permet d’administrer l’aiguillage des requêtes, la balance de charge et le (dé)chiffrement des données en SSL/TLS. De plus les passerelles spécialisées dans la gestion d’APIs proposent des fonctionnalités plus évoluées, telle la mise en place de quotas d’utilisation, la découverte de service, la supervision et les alertes, des tableaux de bord pour l’analytique, l’aiguillage en fonction de la version de l’API demandée et d’autres encore.

Avantages :

  • Moins de responsabilités sur les APIs, elles sont focalisées sur les règles métier

  • Administration uniforme des différentes fonctionnalités, plus facile à maîtriser

  • Point centralisé pour l’administration, souvent proposé dans une interface web

  • Architecture assez simple à concevoir et à maintenir

Inconvénients :

  • Forte adhérence à une solution, dépendant des capacités techniques de celle-ci

  • La passerelle peut être un « single point of failure » ou un goulot d’étranglement, ce qui impacterait l’ensemble du système

  • Les mises à jour doivent souvent être faites de manières globales, pour tous les services de la passerelle

  • L’analytique se base souvent sur l’aspect « ressource » du protocole REST, et non sur l’aspect métier

Les Passerelles Open-source les plus répendues : Tyk, WSO2, API Umbrella, ApiAxle, apigrove, apiman…

Dans la pratique… petit focus sur la passerelle Tyk

Ce projet est divisé en deux outils. D’abord « Tyk Gateway », projet open-source sous licence MPL v2.0, c’est l’application qui joue le rôle de la passerelle. Cette passerelle expose elle même une API REST pour pouvoir être configurée. Ensuite « Tyk Dashboard », qui n’est pas open-source mais est gratuit, permet au travers d’une interface web, d’administrer ses différentes instances de Tyk et voir des tableaux de bord pour la partie analytique. Les points forts de Tyk :

  • Administrable via une API REST, beaucoup de choses peuvent ainsi être automatisées

  • Gestion des utilisateurs et contrôle d’accès, avec une granularité par API, par version d’API, par ressource, par utilisateur, etc

  • Limitation d’utilisation par quota et/ou par débit

  • Création de ressource REST virtuelle, pour par exemple agréger le résultat de plusieurs requêtes via du code Javascript

  • L a transformation à la volée des entêtes ou du corps de la requête HTTP est ici possible

Tyk et la tenue en charge / la disponibilité : Grâce à son aspect « sans état », la tenue en charge d’une API REST est moins complexe à administrer, qu’un service utilisant des affinités de sessions ou du « sharding ». Lorsque la charge devient trop importante, le simple ajout d’une machine hébergeant l’API trop sollicitée peut décharger le système, car celle ci peut être rapidement prise en considération par l’équilibreur de charge placé en frontal. Il en est de même pour la disponibilité, on est en mesure de la renforcer facilement, en répartissant notre API de manière redondante, sur plusieurs machines et/ou centres de données. Tyk intègre les fonctionnalités suivantes pour répondre à cet enjeux :

  • Les nouvelles instances ajoutées au système peuvent être déclarées manuellement, ou de façon automatisée car Tyk offre la possibilité de faire de la découverte de service. C’est aussi lui qui assure de disperser la charge sur toutes les machines.
  • La tenue en charge peut être améliorée via un système de cache, que l’on peut configurer précisément en fonction de la ressource demandée.
  • Un « circuit breaker » automatique, permet de ne plus adresser de requête à l’instance d ‘ une API en mauvaise santé, qui ne répondrait plus que des erreurs par exemple.
  • Il a conscience de la version des APIs fournie par chaque instance, et peut appliquer un aiguillage des requêtes en fonction. Cela aide pour monter de version ses APIs sans coupure de service.
  • Tyk supporte la reconfiguration à chaud, donc sans rupture de service.

Warning : beaucoup de responsabilités sont données à Tyk, il est vital pour votre système car il se place en frontal de tous vos autres services. Il est cependant possible d’améliorer cette situation en créant plusieurs instances de Tyk, afin de ne pas avoir de « single point of failure ».

Tyk et la sécurité : La sécurité d’une API n’est pas du tout gérée de la même façon, si l’on utilise une passerelle ou pas. Sans une passerelle évoluée, chaque API doit être capable de sécuriser ses propres points d’accès. Soit en faisant un appel à une API interne dédiée à ça, soit en utilisant une librairie spécialisée (ex : JAAS, Soring security, apache shiro, SCC…). Tyk adresse le sujet de la sécurité en proposant le support de différentes méthodes (Basic, Jetons d’accès, OAuth2 et JWT), avec des méthodes d’authentification pouvant différer en fonction de l’API sollicitées, avec des contrôles d’accès par version de l’API, par ressource demandée, par méthode HTTP, par quota, par limite du trafic, etc

Tyk et les comptes utilisateurs : En considérant que chaque API utilise ses propres librairies et méthodes d’authentification, toute sorte de combinaisons sont possibles pour gérer ses comptes utilisateurs. Ils peuvent être alimentés dans un annuaire d’entreprise, dans une base de données, etc. Tyk n’a pas, à proprement parler, la notion de compte utilisateur mais utilise des « clés » . Une clé peut représenter à la fois un utilisateur, un groupe d’utilisateur, une application externe, etc. ce point est quelque part la faiblesse actuelle de Tyk qui ne sait pas aller chercher un compte utilisateur dans une ressource externe.

Tyk et la Supervision et les contrats de service : Sans l’utilisation d’une passerelle, il faut faire le choix de composants spécialisés pour assurer la supervision et les contraintes des contrats de service. Tyk permet de gérer ces aspects-là plus simplement. Concernant les Contrats de service Les quotas d’utilisation font partie de la « clé » de l’utilisateur. Ils sont définis lors de sa génération et peuvent ensuite être modifiés, par l’interface « Tyk Dashboard » ou bien par l’API. Une fois le quota atteint, Tyk refusera l’accès à l’API. Un système d’alerte par mail peut être mis en place pour informer un utilisateur qui se rapproche de sa limite d’utilisation.Concernant la Supervision est proposée dans l’interface « Tyk Dashboard » uniquement. On y trouve des graphiques dessinant le taux d’utilisation des APIs par utilisateur, le taux de requête en succès/erreur, la latence moyenne, etc.

Pour conclure

Nous avons vu ce qu’est une API, et en quoi le protocole REST est avantageux pour écrire des services web, notamment par rapport à SOAP. L’utilisation et la mise en œuvre sont simples pour les développeurs, l’administration est simplifiée grâce à sa nature sans état. L’interopérabilité et l’adoption, elles, sont accentuées par l’utilisation des standards, le « versioning » et la possibilité de documenter l’accès à ses services.

L’exploration programmatique des APIs et les outils spécialisés comme les passerelles, aident à industrialiser les besoins communs à ces architectures. Les alternatives open-source de ce genre sont aujourd’hui des composants évolués qui répondent parfaitement aux usages attendus.

Quelques liens pour poursuivre l’exploration 🙂

http://microservices.io/patterns/microservices.html