API REST : Concepts fondamentaux

1. Qu'est-ce qu'une API ? L'analogie du restaurant

Imaginez que vous êtes dans un restaurant.

• Vous (le client) voulez commander un plat.
• La cuisine (le serveur) prépare les plats.
• Vous ne pouvez pas entrer dans la cuisine pour vous servir. Vous avez besoin d'un intermédiaire.

Cet intermédiaire, c'est le serveur du restaurant (l'API). Vous consultez la carte (la documentation de l'API) pour voir ce qui est disponible et comment le demander. Vous passez votre commande (la requête) au serveur, qui la transmet à la cuisine. Une fois le plat prêt, le serveur vous l'apporte (la réponse).

Une API (Application Programming Interface) fonctionne exactement de la même manière : c'est un ensemble de règles et de définitions qui permettent à deux applications logicielles de communiquer entre elles, de manière structurée et prévisible.

Le schéma ci-dessous illustre ce dialogue entre un client (qui demande l'information) et un serveur (qui la fournit) via une API REST.

Pour approfondir cette distinction entre une interface utilisateur (ce que vous voyez à l'écran) et une interface de programmation (ce que les machines utilisent pour parler entre elles), regardez ce court extrait.

2. Les Composants Clés d'une Interaction REST

REST (Representational State Transfer) n'est pas une technologie, mais un style architectural, un ensemble de principes pour concevoir des API. C'est le style le plus répandu aujourd'hui et celui sur lequel reposent les Data Actions de Genesys Cloud.

Pour bien comprendre son fonctionnement, nous allons disséquer les quatre éléments fondamentaux d'une communication REST.

Pour une vue d'ensemble détaillée, je vous propose de lire les sections pertinentes de cet article très complet. Nous y reviendrons au fur et à mesure.

A. L'URL : L'Adresse de la Ressource

Dans une API REST, tout est une ressource. Une ressource peut être un utilisateur, une file d'attente, un client dans un CRM, ou même une conversation spécifique. Chaque ressource est identifiable par une adresse unique, appelée URI (Uniform Resource Identifier), ou plus communément URL.

La structure d'une URL est hiérarchique :

• https://api.mypurecloud.com/api/v2/users : Fait référence à la collection de tous les utilisateurs.
• https://api.mypurecloud.com/api/v2/users/a83b4a44-f655-4b40-a1a3-26b48b3a518c : Fait référence à un utilisateur spécifique, identifié par son ID.

Cette vidéo explique très bien comment les URL sont construites pour cibler des ressources.

B. La Requête : L'Action à Effectuer

Une fois que vous avez l'adresse (l'URL), vous devez dire au serveur ce que vous voulez faire avec cette ressource. Pour cela, on utilise des méthodes HTTP, aussi appelées "verbes". Les quatre principales sont :

Note : Vous rencontrerez aussi la méthode PATCH, qui sert à une mise à jour partielle (par exemple, changer uniquement le numéro de téléphone d'un utilisateur sans toucher au reste).

L'utilisation correcte de ces verbes est un principe clé de REST. On n'utilise pas un GET pour modifier des données, par exemple.

Pour une explication claire de ces méthodes, consultez la section "Les méthodes HTTP utilisées en REST" dans l'article de Stéphane Robert que vous avez ouvert.

C. La Réponse : Le Résultat de l'Opération

Après avoir envoyé votre requête, le serveur vous envoie une réponse. Cette réponse contient deux éléments essentiels :

1. Le Code de Statut HTTP (Status Code)
   C'est un nombre à 3 chiffres qui vous dit si la requête a réussi ou non.

   • 2xx (Succès) : Tout s'est bien passé.
     • 200 OK : Votre GET a réussi, voici les données.
     • 201 Created : Votre POST a réussi, la ressource a été créée.
   • 4xx (Erreur Client) : Vous avez fait une erreur dans votre requête.
     • 400 Bad Request : La requête est mal formée (ex: donnée manquante).
     • 401 Unauthorized : Vous n'êtes pas authentifié.
     • 404 Not Found : La ressource que vous cherchez n'existe pas.
   • 5xx (Erreur Serveur) : Le problème vient du serveur.
     • 500 Internal Server Error : Le serveur a rencontré un problème inattendu.

   Ce bref extrait vidéo résume bien l'idée des codes de statut.

2. Le Corps de la Réponse (Body)
   Si la requête a réussi (par exemple, un GET), le corps contiendra les données que vous avez demandées, le plus souvent au format JSON. Si une erreur s'est produite, il peut contenir des détails sur l'erreur.

   Pour plus de détails, référez-vous à la section "Structure d’une réponse REST" de l'article de Stéphane Robert.

D. JSON : Le Format des Données

JSON (JavaScript Object Notation) est le format de données le plus utilisé dans les API REST. C'est un format texte, léger et facile à lire pour les humains et les machines. Dans Genesys Cloud, c'est le format que vous manipulerez constamment avec les Data Actions.

Un objet JSON est constitué de paires clé-valeur.

• La clé est une chaîne de caractères entre guillemets (ex: "name").
• La valeur peut être une chaîne de caractères, un nombre, un booléen (true/false), un tableau d'autres valeurs, ou même un autre objet JSON.

Voici à quoi pourrait ressembler la réponse JSON pour une requête GET sur un utilisateur Genesys Cloud :

{
  "id": "a83b4a44-f655-4b40-a1a3-26b48b3a518c",
  "name": "Alice Dubois",
  "department": "Ventes",
  "email": "alice.dubois@example.com",
  "state": "active",
  "skills": [
    {
      "name": "Ventes_Francais",
      "level": 5
    },
    {
      "name": "Support_Niveau1",
      "level": 3
    }
  ]
}

Vous pouvez voir des paires clé-valeur simples ("name": "Alice Dubois"), et aussi une clé ("skills") dont la valeur est un tableau d'objets. C'est cette structure que vous apprendrez à "traduire" dans les Data Actions pour extraire les informations dont vous avez besoin.

Conclusion

Félicitations ! Vous venez de découvrir le vocabulaire de base des API REST.

Les points clés à retenir sont :

• Une API REST est un intermédiaire standardisé qui permet aux applications de communiquer.
• On interagit avec des ressources via une URL unique.
• Une requête est composée d'une URL et d'une méthode HTTP (GET, POST, etc.) qui définit l'action à réaliser.
• Le serveur renvoie une réponse qui contient un code de statut (le résultat de l'opération) et un corps (les données).
• JSON est le format de données structuré, basé sur des paires clé-valeur, utilisé pour échanger ces données.

Vous avez maintenant les bases théoriques nécessaires. Votre expérience en administration de centres de contact vous a appris à penser en termes d'objets (agents, files, compétences). Les API REST ne font que vous donner un moyen standard de manipuler ces objets par programme.

Prochaine leçon :

La théorie, c'est bien, mais la pratique, c'est mieux. Dans la prochaine leçon, nous passerons à l'action. Vous utiliserez un outil appelé Postman pour envoyer votre toute première requête à une API publique et analyser la réponse JSON que vous recevrez. Ce sera votre premier pas pratique dans le monde des API.