Uncategorised

API REST : ce qu’un décideur doit comprendre avant un projet d’intégration

Le terme API REST apparaît régulièrement dans les documentations techniques, les logiciels SaaS et les projets d’intégration. Pour un décideur, il n’est pas nécessaire de maîtriser tous les détails de programmation pour comprendre ce que cette architecture permet, ses limites et les questions à poser avant de lancer un projet.

Une API REST peut notamment permettre à deux applications d’échanger des données ou de déclencher certaines actions. Sa présence ne signifie toutefois pas automatiquement que toutes les informations d’un logiciel sont accessibles, que l’intégration sera immédiate ou que les échanges seront sécurisés sans configuration particulière.

Comprendre quelques principes permet donc de mieux cadrer un besoin, lire une documentation API et dialoguer avec les équipes techniques sans transformer le projet en sujet exclusivement informatique.

Qu’est-ce qu’une API REST ?

Une API est une interface permettant à des applications d’échanger des informations ou de demander l’exécution de certaines actions.

REST, pour Representational State Transfer, désigne un style d’architecture permettant d’organiser ces échanges selon plusieurs principes.

Dans les applications Web, les API dites REST ou RESTful utilisent très souvent HTTP, le même protocole qui intervient dans les échanges entre un navigateur et un serveur Web.

REST n’est pas un logiciel ni un protocole

REST ne désigne pas une technologie unique qu’il suffirait d’installer. Il s’agit d’une manière de concevoir les interactions entre différents systèmes.

Dans la pratique, le terme « API REST » est fréquemment utilisé pour désigner une API Web organisée autour de ressources accessibles par des URL et manipulées à l’aide de méthodes HTTP.

Quelle différence entre une API et une API REST ?

Le terme API est beaucoup plus large que le terme API REST.

Une API définit un moyen d’interagir avec un logiciel, un service ou un composant. Plusieurs approches techniques peuvent être utilisées pour proposer cette interface.

REST constitue simplement l’une des architectures courantes pour concevoir des API utilisées sur le Web.

Une API n’est donc pas nécessairement REST

D’autres styles ou protocoles peuvent être utilisés selon les systèmes et les besoins.

Pour un décideur, la question principale n’est généralement pas de déterminer quelle architecture est la plus moderne, mais de savoir :

  • si l’application dispose d’une interface utilisable ;
  • quelles données peuvent être consultées ou modifiées ;
  • quelles actions sont disponibles ;
  • comment l’accès est sécurisé ;
  • quelles contraintes techniques doivent être respectées.

Si vous souhaitez d’abord comprendre la notion générale, notre article Qu’est-ce qu’une API et dans quels cas l’utiliser en entreprise ? présente le principe sans entrer dans l’architecture REST.

Comment une API REST organise-t-elle les données ?

Une API REST est généralement organisée autour de ressources.

Une ressource représente un élément manipulé par l’application : client, utilisateur, commande, dossier, produit ou autre objet correspondant au fonctionnement du logiciel.

Un exemple simplifié

Une API permettant de gérer des clients pourrait proposer une adresse de ce type :

/clients

Elle pourrait servir à récupérer une liste de clients ou à créer un nouveau client selon la méthode utilisée.

Une adresse plus précise comme :

/clients/123

pourrait représenter le client portant l’identifiant 123.

Ces exemples sont volontairement simplifiés : chaque API définit ses propres ressources et ses propres règles.

L’identifiant est important dans une intégration

Lorsqu’une même donnée existe dans plusieurs systèmes, il faut savoir comment les applications vont identifier le même élément.

Une entreprise peut par exemple être identifiée par un numéro interne dans un CRM et par un autre identifiant dans un outil métier.

L’intégration doit alors prévoir le mécanisme permettant de faire correspondre ces références de manière fiable.

À quoi servent GET, POST, PUT, PATCH et DELETE ?

Les API REST utilisent couramment les méthodes HTTP pour indiquer le type d’action demandé.

Sans entrer dans les détails de programmation, quelques méthodes sont fréquemment rencontrées.

GET : consulter une information

Une requête GET sert généralement à récupérer une ressource ou une liste de ressources.

Par exemple : obtenir les informations d’un client ou consulter une liste de dossiers.

POST : créer un nouvel élément

POST est fréquemment utilisé lorsqu’une application doit créer une nouvelle ressource dans un autre système.

Par exemple : créer un contact, un utilisateur ou un dossier.

PUT ou PATCH : modifier une ressource

Ces méthodes servent généralement à mettre à jour des informations existantes.

Leur utilisation exacte dépend de la manière dont l’API a été conçue.

DELETE : supprimer une ressource

DELETE est utilisé lorsqu’une API autorise la suppression d’un élément.

Dans un projet métier, cette possibilité mérite une attention particulière. Une suppression automatique n’est pas toujours souhaitable et peut parfois être remplacée par un changement de statut ou un archivage.

Quels formats de données sont utilisés par une API REST ?

Les API Web modernes utilisent très souvent JSON pour représenter les données échangées.

Un échange pourrait par exemple contenir des informations de ce type :

{
  "id": 123,
  "entreprise": "Exemple",
  "statut": "actif"
}

Ce format permet de transmettre des informations structurées que les applications peuvent ensuite lire et traiter.

JSON n’est pas une obligation de REST

Il est important de distinguer les habitudes courantes des règles absolues.

Une API REST peut utiliser différents formats. JSON est simplement très répandu dans les intégrations Web actuelles.

Les deux logiciels n’utilisent pas toujours la même structure

L’application source peut utiliser le terme « entreprise », tandis que le système cible attend « société » ou organise la donnée différemment.

L’intégration peut donc devoir transformer les informations avant de les transmettre.

C’est notamment l’un des rôles possibles d’un connecteur ou d’un développement intermédiaire.

Comment contrôler l’accès à une API REST ?

Une API exposant des informations ou permettant d’effectuer des actions ne doit généralement pas être accessible sans contrôle.

Plusieurs mécanismes d’authentification peuvent être utilisés selon le service concerné.

Clé API

Certains services fournissent une clé permettant d’identifier l’application qui effectue la demande.

Cette clé doit être protégée comme un identifiant sensible et ne pas être exposée inutilement.

Jetons d’accès

D’autres API utilisent des jetons temporaires ou renouvelables donnant accès à certaines ressources.

OAuth

OAuth est fréquemment rencontré lorsqu’une application doit être autorisée à accéder à certaines informations d’un autre service sans manipuler directement le mot de passe de l’utilisateur.

Les droits doivent être limités au besoin

Une intégration qui doit uniquement consulter certaines informations n’a pas nécessairement besoin d’obtenir le droit de modifier ou supprimer l’ensemble des données.

Le principe consiste à limiter les autorisations aux opérations réellement nécessaires au fonctionnement du projet.

Pourquoi la documentation de l’API est-elle essentielle ?

La présence d’une API dans une brochure commerciale ou une liste de fonctionnalités ne suffit pas pour évaluer la faisabilité d’une intégration.

La documentation permet de comprendre les possibilités réelles du service.

Elle doit permettre d’identifier notamment :

  • les ressources disponibles ;
  • les données accessibles ;
  • les opérations autorisées ;
  • les formats attendus ;
  • le système d’authentification ;
  • les codes d’erreur ;
  • les éventuelles limites de requêtes ;
  • les mécanismes de pagination ;
  • les versions disponibles ;
  • les changements annoncés par l’éditeur.

Une API documentée facilite aussi sa maintenance

Une intégration ne doit pas seulement fonctionner le jour de sa mise en production.

Si l’éditeur modifie son API ou retire une ancienne version, il faut pouvoir identifier les changements et faire évoluer le connecteur lorsque cela devient nécessaire.

Quelles limites d’une API REST faut-il vérifier ?

Une API peut être disponible tout en imposant certaines contraintes d’utilisation.

Le nombre de requêtes

Certains services limitent le nombre d’appels autorisés sur une période donnée.

Cette contrainte peut être peu importante pour quelques synchronisations quotidiennes mais devenir déterminante lorsqu’une application doit traiter un volume important d’informations.

La pagination

Une API peut ne pas retourner plusieurs milliers d’éléments en une seule réponse.

Les données sont alors réparties sur plusieurs pages qu’il faut parcourir successivement.

Les données réellement accessibles

Une application peut disposer de nombreuses informations dans son interface tout en n’exposant qu’une partie de celles-ci dans son API.

Les droits liés à l’abonnement

Certains éditeurs réservent l’accès à l’API ou à certaines fonctions à des offres particulières.

Cette vérification doit intervenir avant le développement afin d’éviter de découvrir tardivement une contrainte contractuelle ou fonctionnelle.

Les versions de l’API

Une API peut évoluer. Une nouvelle version peut modifier certains formats, comportements ou points d’accès.

Il est donc utile de connaître la politique de versionnement et de dépréciation du service utilisé.

Comment gérer les erreurs et les indisponibilités ?

Une API REST renvoie généralement un statut indiquant si la demande a été correctement traitée.

Les codes HTTP permettent notamment de distinguer différentes situations.

Quelques familles de réponses courantes

  • 2xx : la demande a généralement été traitée correctement ;
  • 4xx : un problème concerne généralement la demande ou les droits d’accès ;
  • 5xx : le service distant rencontre généralement un problème pour traiter la demande.

Ces catégories permettent au développement de réagir différemment selon le type d’erreur.

Une intégration doit prévoir les scénarios d’échec

Il faut notamment déterminer :

  • si une nouvelle tentative doit être effectuée ;
  • combien de fois elle peut être répétée ;
  • comment éviter de créer des doublons ;
  • quelles informations doivent être enregistrées dans les journaux ;
  • quand un utilisateur doit être averti ;
  • comment reprendre un traitement interrompu.

Ces choix deviennent particulièrement importants lorsqu’une API participe à un processus métier automatisé.

Une API REST est-elle automatiquement sécurisée ?

Non. Le fait qu’une API utilise une architecture REST ne garantit pas sa sécurité.

La sécurité dépend de sa conception, de son hébergement, de ses mécanismes d’authentification, des autorisations accordées et de la manière dont les applications clientes l’utilisent.

Plusieurs éléments doivent être examinés

  • utilisation de connexions chiffrées ;
  • protection des identifiants et secrets ;
  • gestion des authentifications ;
  • contrôle des autorisations ;
  • validation des données reçues ;
  • gestion des journaux ;
  • limitation des accès ;
  • maintenance et mises à jour.

Les recommandations de l’OWASP consacrées à la sécurité des API fournissent notamment une liste de risques fréquents à prendre en compte lors de la conception et de l’exploitation de ces interfaces.

Que doit vérifier un décideur avant un projet d’intégration API REST ?

Avant de lancer le développement, le projet peut être cadré avec une série de questions simples.

1. Quel problème métier voulons-nous résoudre ?

Évitez de commencer par « nous voulons utiliser l’API ». Commencez plutôt par le processus concerné : double saisie, synchronisation, déclenchement d’une action, centralisation d’informations ou autre difficulté concrète.

2. Quels logiciels doivent communiquer ?

Identifiez précisément les systèmes concernés et leur rôle.

3. Quelles données doivent circuler ?

Listez uniquement les informations réellement nécessaires au processus.

4. Quel logiciel constitue la référence ?

Lorsqu’une donnée existe dans plusieurs systèmes, il faut déterminer lequel est responsable de sa création et de sa mise à jour.

5. Les API permettent-elles les opérations nécessaires ?

Cette question doit être vérifiée dans la documentation technique et, si nécessaire, au moyen de tests.

6. À quelle fréquence les échanges doivent-ils intervenir ?

Un besoin en temps quasi réel et une synchronisation quotidienne ne nécessitent pas forcément la même architecture.

7. Que doit-il se passer en cas d’erreur ?

Le comportement attendu doit être défini avant la mise en production.

8. Comment l’intégration sera-t-elle maintenue ?

Les API et logiciels connectés peuvent évoluer. La maintenance doit donc être envisagée dès le départ.

Notre article consacré à l’intégration API entre plusieurs applications développe plus précisément cette phase de cadrage autour des données et des processus.

AMEGANET accompagne également les entreprises dans leurs projets de développement sur mesure, API, connecteurs et automatisations.

Questions fréquentes sur les API REST

Quelle est la différence entre REST API et API REST ?

Il s’agit généralement de deux formulations utilisées pour désigner la même notion. « REST API » correspond à la formulation anglaise et « API REST » est couramment utilisée en français.

Une API REST utilise-t-elle toujours JSON ?

Non. JSON est très courant dans les API Web modernes, mais REST n’impose pas ce format. Le format utilisé dépend de la conception de l’API et des besoins du service.

Une API REST fonctionne-t-elle forcément en temps réel ?

Non. Une API permet de réaliser des échanges mais la fréquence dépend de l’intégration. Les appels peuvent être déclenchés immédiatement après une action, exécutés périodiquement ou lancés à la demande.

Peut-on modifier toutes les données d’un logiciel avec son API REST ?

Pas nécessairement. L’éditeur décide quelles ressources et quelles opérations sont exposées. Certaines informations peuvent être consultables mais non modifiables, voire totalement absentes de l’API.

Une API REST est-elle adaptée pour connecter deux logiciels ?

Elle peut l’être lorsque les API des applications offrent les ressources et opérations nécessaires. La faisabilité doit être étudiée à partir du processus, des données à échanger et de la documentation disponible. Notre guide sur l’intégration API détaille cette démarche.

API REST, connecteur et automatisation désignent-ils la même chose ?

Non. Une API REST constitue une interface d’échange. Un connecteur peut exploiter une ou plusieurs API pour adapter les échanges entre des applications. Une automatisation utilise des règles pour déclencher ou enchaîner certaines actions. Ces éléments peuvent être utilisés ensemble dans un même projet.

Pour approfondir les API et l’intégration

Plusieurs ressources AMEGANET complètent les notions abordées dans cet article :

Ce qu’il faut retenir avant d’utiliser une API REST

Une API REST constitue une manière courante de permettre à des applications Web et des logiciels d’échanger des informations.

Pour un décideur, l’essentiel n’est pas de maîtriser chaque détail du protocole HTTP mais de comprendre ce que l’API permet réellement : données accessibles, actions disponibles, authentification, limites, erreurs et conditions d’évolution.

Cette analyse permet de distinguer une API théoriquement disponible d’une API réellement adaptée au processus métier à mettre en place.

Le développement peut ensuite être conçu autour des usages plutôt qu’autour de la technologie elle-même.

Vous devez intégrer une API REST à votre environnement ?

AMEGANET peut étudier les applications concernées, leur documentation API et les données à échanger afin de définir l’intégration, le connecteur ou le développement spécifique adapté à votre processus.

Présenter votre projet d’intégration API

Sources et ressources

Les notions techniques présentées dans cet article peuvent notamment être approfondies dans les documentations et références suivantes.