Les APIs ReST

LES APIs REST

 

REST is used to build Web services that are lightweight, maintainable, and scalable in nature. A service which is built on the REST architecture is called a RESTful service. The underlying protocol for REST is HTTP, which is the basic web protocol. REST stands for REpresentational State Transfer

  • It enables web applications that are built on various programming languages to communicate with each other
  • With the help of Restful services, these web applications can reside on different environments, some could be on Windows, and others could be on Linux.

But in the end, no matter what the environment is, the end result should always be the same that they should be able to talk to each other. Restful web services offer this flexibility to applications built on various programming languages and platforms to talk to each other.

Facebook, Twitter, and Google expose their functionality in the form of Restful web services. This allows any client application to call these web services via REST.

 

QU’EST CE QU’UNE API?

De manière générale, les APIs permettent aux programmes informatiques de « se parler » entre eux pour demander et fournir des informations.

DEFINITION

API est l'acronyme d'Application Programming Interface, que l'on traduit en français par interface de programmation applicative ou interface de programmation d'application. L'API peut être résumée à une solution informatique qui permet à des applications de communiquer entre elles et de s'échanger mutuellement des services ou des données. Il s'agit en réalité d'un ensemble de fonctions qui facilitent, via un langage de programmation, l'accès aux services d'une application.

Une API permet donc à deux systèmes informatiques totalement indépendants de se parler de façon automatique. Plus précisément, une API est le mode d’emploi qui permet à un système informatique de faire appel à des fonctionnalités d’un autre système informatique : elle permet donc de les rendre interoperables entre eux.

Dit autrement, l’API est ce qui permet à un programme informatique de profiter des fonctionnalités d’un autre programme informatique, tout autant que votre écran (associé à une souris et un clavier s’il n’est pas tactile) est ce qui vous permet de profiter des fonctionnalités d’un programme informatique

 

DOMAINES D'APPLICATION DE L'API

Dans le domaine d'internet, l'API permet aux développeurs de pouvoir utiliser un programme sans avoir à se soucier du fonctionnement complexe d'une application. Les API peuvent par exemple être utilisées pour déclencher des campagnes publicitaires d'e-mailing de façon automatique sans avoir à passer par la compréhension d'une telle application (c'est le cas avec l'API AdWords de Google, par exemple). On les retrouve aujourd'hui dans de nombreux logiciels, en particulier dans les systèmes d'exploitation, les serveurs d'applications, dans le monde du graphisme, dans les applications SaaS, les bases de données, l'open data, etc.

Une API permet de fournir un certain niveau d’abstraction au développeur, c’est-à-dire qu’elle lui masque la complexité de l’accès à un système ou à une application en proposant un jeu de fonctions standard dont seuls les paramètres et les valeurs retournées sont connus.

Grâce aux API, un développeur n’a donc pas à se soucier de la façon dont une application distante fonctionne, ni de la manière dont les fonctions ont été implémentées pour pouvoir l'utiliser dans un programme. Une API peut être disponible pour un langage particulier ou bien être disponible pour plusieurs langages de programmation.

 

Etant donné que dans notre écosystème moderne, les applications sont de moins en moins monolithiques et qu’il y a de plus en plus d’interactions entre les services afin de fournir un produit intéressant, les APIs se doivent d’être :

  • Flexibles, extensibles et réutilisables,
  • Faciles à utiliser et compréhensibles,
  • Conformes à la "Separation of Concerns",
  • Compatibles avec le plus de technologies possibles (Il faut pouvoir développer des clients et des serveurs légers)
  • Performantes et sécurisées.

 

LES DIFFERENTS TYPES D'API

Il existe deux grands protocoles de communication sur lesquels s'adossent les APIs : Simple Object Access Protocol (SOAP) et Representational State Transfer (ReST). Le second s'est désormais largement imposé face au premier car il est plus flexible. Il a donné naissance aux APIs dites REST ou RESTful.

 

SOAP et REST sont donc deux solutions permettant à un client d’accéder à des services web. D’un côté, SOAP, initialement développé par Microsoft, est un protocole d'accès aux services Web qui existe depuis un certain temps. De l’autre, l’architecture REST est la nouvelle venue. Elle vise à résoudre certains problèmes rencontrés avec SOAP et donner la possibilité de mettre en place une méthode vraiment simple afin d’accéder à des services web.

 

 

REPRESENTATIONAL STATE TRANSFER

REST est un moyen d'accéder aux documents et aux ressources distants selon une architecture logicielle simple, représentée par une API. On dit "RESTful" les sites utilisant ce modèle de communication.

Créée par Roy Fielding en 2000, REST est un acronyme pour Representational State Transfer. Souvent associée à l'architecture orientée service, cette architecture est un moyen de présenter et manipuler des ressources.

Notez que Roy Fielding est aussi l’un des 8 fondateurs de la fondation Apache, il a travaillé sur le Apache HTTP Server et a aidé à développer les premiers serveurs Web. Dans sa thèse, Roy Fielding défini ainsi un ensemble de principes qui constituent l’architecture REST.

Les premières choses à retenir sur l’architecture REST sont :

  • REST est un ensemble de conventions et de bonnes pratiques à respecter pour la conception de services Web
  • C’est un style d’architecture
  • C’est une approche pour construire une API
  • Mais ce n’est ni un protocole, ni un standard, ni une technologie à part entière
  • REST est une architecture basée sur les normes Web et utilise le protocole http
  • REST est un moyen d'accéder aux ressources situées dans un environnement particulier.

Comme l’a dit Roy Fielding dans le chapitre 6 de sa thèse, l’objectif de REST était de créer un modèle architectural décrivant comment le web devrait fonctionner, le permettant de devenir ainsi une référence pour les protocoles web. REST a été conçu en évitant de violer les contraintes principales qui régissent le web.

 

COMMENT FONCTIONNE REST

Les APIs REST imitent la façon dont le web lui-même marche dans les échanges entre un client et un serveur.

Ainsi, des commandes HTTP permettent d'accéder aux ressources d'un serveur :
GET est utilisé pour créer une nouvelle ressource et pour requérir des données, par exemple charger une page, en envoyant des paires clé/valeur dans l'URL.
POST est utilisé pour créer une nouvelle ressource et pour envoyer des données au serveur, par exemple les données d'un formulaire, dans le message HTTP (et non l'URL) où un script les traite.
PUT est utilisé pour mettre à jour une ressource existante ou créer une nouvelle ressource et DELETE est utilisé pour supprimer une ressource.

On accède donc à une ressource (par son URI unique) pour procéder à diverses opérations (GET lecture / POST écriture / PUT modification / DELETE suppression), opérations supportées nativement par HTTP.

 

DEFINITION D’UNE RESSOURCE

Une interface REST gravite autour de ressources. À partir du moment où vous devez interagir avec une entité de votre application, créer une entité, la modifier, la consulter ou encore l’identifier de manière unique, vous avez pour la plupart des cas une ressource. Une ressource est un objet ou plusieurs objets auquel les utilisateurs de votre API peuvent vouloir accéder.

Pour référencer de manière unique cette ressource, REST utilise un identifiant. Cet identifiant sera alors utilisé par tous les différents composants de notre application afin d’interagir avec cette ressource. La première partie de l'URI est toujours la ressource. Si vous ajoutez des éléments supplémentaires à l’URI, vous recevrez une réponse plus précise.

REST se base donc sur les URI (Uniform Resource Identifier) afin d’identifier une ressource. Ainsi une application se doit de construire ses URI (et donc ses URL) de manière précise, en tenant compte des contraintes REST.

 

LES CRITERES REST

REST est un style d’architecture défini par un ensemble de contraintes qui régissent l’organisation d’une application et les procédés de communication entre un fournisseur de services (le serveur) et le consommateur (le client).

Six contraintes architecturales définissent un système REST. Un système qui viole une de ces contraintes ne peut pas être considéré comme adhérant à l'architecture REST.

  • Sans état
  • Cacheable (avec cache = mémoire)
  • Orienté client-serveur
  • Avec une interface uniforme
  • Avec un système de couche
  • Un code à la demande (optionnel)

Le principe du client-serveur définit les deux entités qui interagissent dans une API REST : un client et un serveur, les mêmes entités qui communiquent sur le web. Un client envoie une requête, et le serveur renvoie une réponse. Ce dernier doit avoir le plus d’informations possible sur le client, car il est important qu’ils soient capables de travailler indépendamment l’un de l’autre.

Contrairement aux applications Web, les API RESTful sont généralement sans état, ce qui signifie que les sessions ou les cookies ne doivent pas être utilisés. Par conséquent, chaque demande doit être accompagnée d’une sorte d’identifiant d’authentification. Une pratique courante consiste à envoyer un jeton d'accès secret à chaque demande d'authentification de l'utilisateur. Dans la mesure où un jeton d'accès peut être utilisé pour identifier et authentifier de manière unique un utilisateur, les demandes d'API doivent toujours être envoyées via HTTPS afin de prévenir les attaques par interception.

Le fait d’être “sans état” signifie que le serveur n’a aucune idée de l’état du client entre deux requêtes. Du point de vue du serveur, chaque requête est une entité distincte des autres.

Ensuite, le cache, pour les API REST, met en jeu le même principe que pour le reste d’Internet : un client doit être capable de garder en mémoire des informations sans avoir constamment besoin de demander tout au serveur. Ce sont les concepts de base à comprendre sur REST, nous verrons les autres lorsque vos projets deviendront plus complexes.

Les réponses du serveur pour les API REST peuvent être délivrées dans de multiples formats. JSON (JavaScript Object Notation) est souvent utilisé, mais XML, CSV, ou même RSS sont aussi valables.

Pour finir cette partie, voici ce que les contraintes architecturales de REST confèrent aux systèmes qui les respectent les propriétés architecturales suivantes :

  • Performance dans les interactions des composants, qui peuvent être le facteur dominant dans la performance perçue par l'utilisateur et l'efficacité du réseau8 ;
  • Extensibilité permettant de supporter un grand nombre de composants et leurs interactions.
  • Simplicité d'une interface uniforme ;
  • Évolutivité des composants pour répondre aux besoins (même lorsque l'application est en cours de fonctionnement) ;
  • Visibilité des communications entre les composants par des agents de service ;
  • Portabilité des composants en déplaçant le code avec les données ;
  • Fiabilité dans la résistance aux pannes du système en cas de pannes des composants, des connecteurs ou des données.

 

MODELE DE MATURITE DE RICHARDSON:

Le modèle de maturité de Richardson est un moyen d’évaluer votre API par rapport aux contraintes de REST.

Selon le modèle de maturité de Richardson il existe quatre grands niveaux d’évaluation d’une API. Au plus on atteint un niveau élevé au plus notre API est considérée comme RESTful et respecte ce qu’on appelle communément les “bonnes pratiques”.

Le niveau 0 est une API qui qu’on ne peut pas qualifier d’API REST. Ce niveau s’apparente davantage à ce que l'on peut retrouver dans une API de type SOAP. Considéré comme la base minimale, Il s'agit de n'utiliser qu'un seul point d'entrée pour communiquer avec l'API. Une URI unique est mise en place, comme par exemple “/api”, de même qu'une seule méthode HTTP n’est utilisée afin d’effectuer ses demandes, il s’agit de POST. Toutes les requêtes sont de type POST et sont effectués vers la même URI.

·         Niveau 1 : l’utilisation de ressources différenciées

Dans le Richardson Maturity Model, le premier pas vers l’utilisation de REST consiste à introduire la notion de ressource. Ce qui est somme toute assez logique, puisque REST est un modèle d’architecture basé sur la manipulation de ressources (tout est ressource).

Ainsi, là où au niveau 0, toutes les requêtes étaient faites vers un unique endpoint (une unique URI), au niveau 1, les requêtes sont envoyées à des ressources individuelles

Lorsque votre API permet de distinguer différentes ressources, elle peut être de niveau 1. Ce niveau utilise plusieurs URIs, où chaque URI est le point d’entrée vers une ressource spécifique. Au lieu de passer par http://example.org/articles, vous pouvez faire la distinction entre http://example.org/article/1 et http://example.org/article/2.

  • Niveau 2 : L’utilisation des verbes et des codes retours HTTP

La deuxième étape de l’approche prônée par le Richardson Maturity Model est d’introduire l’utilisation des verbes et des codes retours HTTP. Dans REST, les ressources sont manipulées au travers d’un jeu de verbes simples. Le plus souvent les verbes HTTP pour la simple et bonne raison que la majeure partie des implémentations REST se fait sur HTTP.

L’idée est de tirer parti du protocole sur lequel nous nous appuyons.

N’utilisez pas une seule méthode [POST] pour tout, mais utilisez [GET] pour récupérer des ressources, et [DELETE] pour supprimer des ressources. De plus, utilisez les codes de réponse du protocole utilisé par votre application. Par exemple, n’utilisez pas le code [200] (OK) lorsque quelque chose se passe mal. En procédant ainsi avec le protocole HTTP, ou tout autre protocole que vous avez envie d’utiliser, vous aurez atteint le niveau 2.

·         Niveau 3 : L’utilisation des contrôles hypermédia

Le troisième et dernier niveau du Richardson Maturity Model introduit la notion de HATEOAS (Hypertext As The Engine Of Application State). Derrière cet acronyme barbare se cache un principe simple : les transitions possibles vers les états suivants sont fournies par des liens hypermédia.

Les requêtes sont les mêmes qu’au niveau 2, mais les réponses sont ici enrichies avec, pour chaque ressource, un élément link fournissant l’URI permettant de la manipuler.

Hypermedia est l’une des principales règles de la thèse de Fielding. L’idée est de retrouver dans les API ReST la même logique Hypermedia qu’en HTML par exemple. Aujourd’hui, cela se résume principalement par la présence de liens dans les ressources permettant de définir la relation avec d’autres ressources. L’API ReST devient alors "discoverable".

Le niveau 3 est donc simplement l'idée de rendre votre API auto découvrable, en imitant les liens hypertextes dans une page web classique. Concrètement, nous devons indiquer au client de votre API ce qu'il est possible de faire à partir d'une ressource.

 

LES FORMATS D'ECHANGE

En théorie, le format d’échange est libre. En pratique, le format doit être standard et non-linéaire (Hypermedia).

Plus concrètement, le format le plus utilisé aujourd’hui est le JSON (JavaScript Object Notation) car :

  • L’univers JavaScript est en expansion permanente,
  • Contrairement aux technologies backend habituelles, le nombre de librairies et d’outils utilisés est volontairement restreint pour éviter de surcharger les clients JavaScript,
  • On retrouve des outils JSON dans tous les langages,
  • Le JSON est facile et rapide (au sens performance) à manipuler,
  • Le JSON est "human-readable".

EXEMPLE PRATIQUE

Voyons tout de suite à quoi ressemble l’utilisation d’une API RestFul avec Watson, le service d’intelligence artificielle d’IBM qui convertit un fichier audio en texte.

Sur le site d’IBM Cloud, après avoir créé un compte et sélectionné le service « Speech to text », un tutoriel d’initiation est proposé ainsi qu’un mini-tutoriel pour essayer un appel d’API, comme vous pouvez le voir ci-dessous :

 

Pour tester cette solution, nous pouvons utiliser cURL. cURL veut dire "Client URL Request Library", ou encore "see URL". Ce logiciel est une interface en ligne de commande conçue pour récupérer le contenu d'une ressource accessible par un réseau informatique.

Il suffit d’ouvrir son terminal pour voir ce que le service renvoie, et voici le résultat :

 

L’API nous renvoie au format JSON la retranscription de notre fichier audio ! En effet, JSON est rapidement devenu le format de choix pour les API REST. Il a une syntaxe légère et lisible qui peut être facilement manipulée.

Vous noterez que mes identifiants sont cachés mais pour interagir avec les APIs il faut bien sûr s’authentifier.

Dans cette commande, -u  indique que vous avez un nom d'utilisateur et mot de passe qui suivent, -X  indique que nous allons préciser une méthode HTTP à utiliser dans la communication avec le serveur, et ici, nous utilisons POST ; Les informations après --header sont les contenus à inclure dans l'en-tête de la requête. En général --data-binary  indique qu’on va transmettre des données au serveur, et comme les données qu’on envoie sont dans un fichier audio, nous précisons aussi l’endroit du fichier sur notre ordinateur. Enfin, nous fournissons l’URL de l’API.

 

Si je me trompe dans le chemin URL j’aurai un code d’erreur tout comme avec le protocole http :

 

En effet, une autre partie importante de REST consiste à répondre avec le code d'état correct pour le type de demande qui a été faite.

QUELQUES OUTILS INTERESSANTS SUR LE WEB AUTOUR DES APIs REST :

  • Swagger : Swagger est un framework qui vous permet de définir (conformément au standard OpenAPI), documenter vos APIs ReST et générer du code.
  • Postman : Postman est un client ReST très pratique pour analyser, expérimenter et debug vos APIs ReST. Pensez à essayer l’extension Chrome qui permet d’analyser le trafic et rejouer les requêtes.
  • Sandbox : Le meilleur terrain de jeu pour s’amuser avec les APIs ReST.
  • JSON generator : JSON Generator vous permet de générer facilement des données JSON pour vos tests unitaires par exemple.
  • JSON-Server : JSON-Server est un simple outil permettant de générer des fausses APIs à des fins de démonstration par exemple.
  • Any Api : Documentation et consoles de test pour plus de 500 API publiques
  • JSONPlaceholder : Fausse API REST en ligne pour le test et le prototypage
  • Go rest : API REST GRATUITE en ligne pour le test et le prototypage d'applications Web et Android (dispose aussi d’une console pour tester ses requêtes).
  • REST test test, et j’en passe, n’hésitez pas à aller fouiller davantage sur le web !

 

 

RESSOURCES UTILISÉES

  • Wikipedia
  • Thèse de Roy T. Fielding
  • Openclassrooms

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *