API 101 - Présentation de base des API

Dernière mise à jour : 2023-07-26
  • Créé pour :
  • Beginner
    User
    Developer

API signifie Application Programming Interface. Ça signifie exactement ce qu'il dit : il y a des interfaces entre les programmes et ces interfaces permettent à ces programmes de communiquer. Lorsque les programmeurs développent des applications logicielles, ils ont souvent besoin de leur logiciel pour communiquer avec d'autres logiciels ou matériels. L’API définit les éléments suivants : quoi, comment, quand, où et pourquoi pour ces communications et interactions.

Les API sont un moyen de résoudre les problèmes métier liés aux logiciels. Dans la plupart des entreprises, c'est un effort collaboratif. Collaborer est toujours plus facile avec une compréhension partagée des termes, concepts et étapes clés.

Si vous envisagez de cliquer sur un lien d’une page web, le navigateur utilise plusieurs API lorsque vous cliquez sur le lien. Le navigateur reconnaît le clic, demande la page que vous souhaitez consulter, récupère la page sur Internet, puis l’affiche à l’écran. Il existe de nombreuses petites étapes intermédiaires, mais votre navigateur est un logiciel qui communique et interagit avec diverses API simplement pour vous montrer une page web. Dans cet article, nous allons mettre en évidence les termes, concepts et étapes importants lors de l’utilisation ou de la discussion d’API.

À la fin de cet article, vous devriez avoir une compréhension claire de ces termes, concepts et étapes fondamentaux. La documentation des API peut être exhaustive et les discussions sur l’utilisation des API pour traiter des cas d’utilisation spécifiques peuvent être très détaillées. La navigation dans la documentation et la discussion des API est plus facile et plus productive grâce à des fondamentaux clairs et une compréhension partagée.

REMARQUE

Bien qu’il y ait de nombreuses API, l’accent sera mis ici sur les API Web et de navigateur : en fait, lorsqu’une application logicielle interagit avec une autre sur Internet.

Termes et concepts de l’API

Que signifie un mot ou une expression, et comment puis-je y penser simplement et facilement ? Dans une API, la partie "application" signifie une application ou un programme logiciel. La partie "interface de programmation" fait référence à la manière et à l’endroit où une application interagit avec une autre application à certaines fins. Dans notre exemple de page web, lorsque vous cliquez sur un lien, le navigateur envoie une demande à un serveur pour la page web.

Image du lien hypertexte avec l’URL de destination

Dans cette capture d’écran, le curseur de la souris survole le lien Adobe Experience Platform. En bas se trouve la barre d’état du navigateur web qui indique "l’adresse" de la page que le navigateur obtiendra. En d’autres termes, cliquer sur le lien Adobe Experience Platform indique au navigateur d’"obtenir cette page pour que je puisse la voir ici sur mon écran".

Lorsqu’un utilisateur clique sur un lien, le navigateur envoie une requête à un serveur pour obtenir une page. Ceci est une GET request, l’une des méthodes de requête couramment utilisées avec les API web. Une chose dont le navigateur a besoin pour répondre à la demande est l’"adresse" de la page - où se trouve-t-il sur le web ?

Parties d’une URL

Barre d’adresse du navigateur avec URL

La plupart des navigateurs ont une "barre d’adresse" qui affiche une partie ou la totalité de l’"adresse" d’une page web. Lorsque le navigateur "récupère" la page du lien sur lequel nous avons cliqué, il affiche "l’adresse" de la page dans cette barre d’adresse. Quelle est donc l'"adresse" d'une page web ?

Cela https://business.adobe.com/products/experience-platform/adobe-experience-platform.html ci-dessus correspond à l’adresse d’une page sur le Web, appelée URL ou localisateur de ressource Uniform. Les URL peuvent faire référence à une page telle que celle-ci, un fichier image, une vidéo ou d’autres types de fichiers.

Parties d’une URL

Cette adresse, l’URL, comporte des parties spécifiques qui sont très pertinentes pour les API web et de navigateur.

Schéma

La variable scheme ci-dessus est également appelé protocol avec les API web et c’est généralement soit http ou https. Le protocole de transfert HTTP ou HyperText est la manière dont les ressources telles que les pages web sont transférées d’un serveur web à un navigateur web. HTTPS est la version sécurisée, où le transfert se produit sur Internet à l'aide de la sécurité destinée à empêcher toute interférence avec la ressource qui est transférée. Il est courant de voir une petite icône de verrouillage dans la barre d’adresse du navigateur lors de l’affichage d’une page via HTTPS.

Pour les API web, les transferts de ces ressources se font par le biais de requêtes HTTP, c’est-à-dire des requêtes via HTTP.

Hôtes et domaines

La variable business.adobe.com est l’hôte de la ressource demandée. Lorsque vous cliquez sur notre exemple de lien, le navigateur utilise cette partie de l’URL pour trouver le serveur sur lequel la page est hébergée. Ce n’est pas toujours exactement la même chose que le serveur web, mais à un niveau de base, nous pouvons le considérer comme le serveur où le navigateur obtiendra la page que nous avons demandée.

Les noms de domaine font partie du système de noms de domaine, plus connu sous le nom de DNS. La plupart des gens pensent à adobe.com ou example.com comme "nom de domaine", mais il existe des parties pertinentes pour les API. www.adobe.com et business.adobe.com peut être appelé noms de domaine, mais la variable www. et la variable business. les parties sont appelées sous-domaines. Les API interagissent souvent avec une URL qui inclut un sous-domaine comme api.example.com ou sub.www.example.com.

Il est très courant de voir le terme hôte faire référence à un nom de domaine complet, y compris tout sous-domaine comme business.adobe.com. Il est également courant de voir les termes domain ou nom de domaine en cas de référence à un hôte sans sous-domaine, comme adobe.com. Il n’est pas important ici de mémoriser les termes spécifiques pour chaque partie et variation d’un hôte. Mais il est important de savoir que ces termes sont couramment utilisés afin de pouvoir clarifier les détails pertinents de votre entreprise et de vos discussions.

Origine

Origin est un autre terme qui est lié aux parties d’une URL. À un niveau de base, une origine correspond approximativement à la valeur scheme plus le host plus le domain like https://business.adobe.com. Les différentes valeurs représentent souvent des origines différentes, telles que https://business.adobe.com et http://business.adobe.com ne sont pas de même origine parce qu'ils ont des schémas différents. https://www.adobe.com et https://business.adobe.com ne sont pas non plus la même origine dans de nombreux usages en raison des différents sous-domaines.

Path

La dernière partie de l’exemple d’URL ci-dessus est la path à la ressource : la page dans notre exemple. La variable /products/experience-platform/ représente généralement des dossiers ou des répertoires sur le serveur web. Tout comme nous avons des dossiers ou des répertoires sur nos ordinateurs pour les documents et les photos, nous avons aussi des dossiers sur les serveurs web pour organiser le contenu. Et enfin, le /adobe-experience-platform.html part est le nom du fichier, c’est-à-dire la page web.

D’autres parties plus détaillées d’une URL seront mises en évidence dans la partie suivante de cette série.

API tierces

Les API Web sont parfois appelées API tierces. Pensez à ceci comme aux parties impliquées dans une transaction. Dans notre exemple de lien, vous (ou plus spécifiquement votre navigateur), êtes le premier dans la requête de la page. Le serveur web est le second. Où est le troisième ?

Il est courant qu’une page web contienne du contenu ou des ressources provenant d’autres hôtes ou sources. Dans ce cas, lorsque votre navigateur commence à afficher la page, il envoie un autre ensemble de requêtes à ces autres hôtes, ou "tiers", qui hébergent ces ressources. C’est très courant, en particulier pour le contenu multimédia tel que les vidéos ou les images, mais aussi pour les données qui doivent être mises à jour au moment de leur affichage ou de leur utilisation. L’obtention de l’heure actuelle, de la météo actuelle ou d’un message de bienvenue personnalisé pour une personne spécifique sont autant d’exemples où une API tierce peut fournir la ressource appropriée au bon moment. Il est courant que ces requêtes proviennent de ces API tierces.

Utilisations courantes des API web

Outre l’heure, la météo ou le contenu personnalisé, il existe de nombreuses utilisations pour les API web. Les plateformes de médias sociaux comme Twitter, TikTok, Facebook, LinkedIn, Snapchat, Pinterest et d’autres disposent d’une variété d’API que les programmeurs peuvent utiliser avec leurs applications. Et bien sûr, l'Adobe a aussi une grande variété d’API ; que les programmeurs utilisent pour que leurs logiciels puissent interagir avec les produits et services Adobe. Les produits et services logiciels accèdent à d’autres produits et services logiciels par l’intermédiaire de ces API.

Exemples d’API

Les API de navigateur permettent aux programmeurs d’interagir directement avec les fonctionnalités du navigateur. L’API de batterie permet au logiciel de vérifier l’état de la batterie d’un appareil afin qu’il puisse vous alerter si nécessaire. L’API Presse-papiers permet au logiciel de copier ou coller le contenu avec le Presse-papiers de votre périphérique. L’API plein écran permet aux logiciels de présenter l’option permettant d’afficher la vue en plein écran de l’appareil, comme YouTube.

L’API Adobe Experience Platform Data Access est une API web qui permet aux programmeurs d’accéder aux fichiers de jeux de données de Adobe Experience Platform et de les télécharger afin qu’ils puissent utiliser les données de profil client dans leurs propres programmes. Il est très courant que des API comme celle-ci fassent partie d’un processus d’automatisation logicielle où le logiciel est programmé pour effectuer une séquence d’étapes en utilisant plusieurs API en combinaison. Il peut s’agir souvent d’une économie de coûts importante par rapport à l’exécution manuelle de ces mêmes étapes.

Points de terminaison API

Lorsque les programmeurs "utilisent" un navigateur ou une API web dans leurs programmes, ils envoient généralement des requêtes pour envoyer ou recevoir des ressources, comme notre exemple de navigateur demandant une page web. La documentation de l’API répertorie souvent des "points de terminaison" pour ces requêtes, par exemple : https://platform.adobe.io/data/foundation/export/files/{dataSetFileId}. Il s’agit du modèle spécifique ou "point de terminaison" de l’API d’accès aux données de Platform qu’un programmeur utilisera pour obtenir un fichier de jeu de données.

La variable {dataSetFileId} entouré de ces accolades représente une valeur que le programmeur doit envoyer dans la requête. Ainsi, l’URL de la requête API réelle ressemblerait à https://platform.adobe.io/data/foundation/export/files/xyz123brb où la variable xyz123brb doit être un identifiant valide du fichier de jeu de données que le programmeur souhaite recevoir.

En d’autres termes, tout comme le navigateur obtient une page à une URL spécifique, les requêtes d’API obtiennent des ressources d’un point de terminaison spécifique, ou en envoient des vers, comme cet exemple de jeu de données.

Méthodes de requête HTTP

À ce stade, il devrait être clair que les API web effectuent des demandes de ressources telles que des pages web ou des jeux de données. Comme la plupart des concepts logiciels, ces requêtes HTTP suivent des modèles répétables. Une demande est envoyée d’une application logicielle à une autre application logicielle qui évalue la demande, puis répond : le navigateur demande une page à un serveur web et répond avec le contenu de la page.

L’ensemble du processus, de la demande à la réponse, implique de nombreuses étapes plus petites et très détaillées, mais les méthodes de la demande sont simples. Les méthodes de requête définissent l’opération demandée.

GET

La variable GET La méthode de requête est utilisée lors de la demande d’une réponse qui fournit une ressource, comme notre page web et des exemples de jeux de données. Lorsque nous cliquons sur un lien dans un navigateur ou appuyez sur un lien sur un périphérique mobile, nous créons un événement GET demande en coulisses.

POST

La variable POST envoie des données avec la requête. Il peut sembler étrange qu’une "requête" envoie des données, mais l’idée est que l’exécution de la requête API demande au point de terminaison (le logiciel de réception) d’accepter la requête, et dans le cas d’une POST, afin d’accepter également les données envoyées. Les données envoyées sont généralement écrites dans un entrepôt de données, tel qu’une base de données ou un fichier, afin de pouvoir être enregistrées.

PUT

La variable PUT la méthode de requête est similaire à POST puisqu’il envoie des données, mais si les données envoyées existent déjà au point de terminaison, un PUT mettra à jour les données existantes en les remplaçant. A POST ne se met pas à jour, envoie simplement plusieurs POST les demandes peuvent créer plusieurs enregistrements des données envoyées, au lieu de mettre à jour un enregistrement existant.

PATCH

La variable PATCH La méthode de requête est utilisée pour envoyer des données qui mettent à jour une partie d’un enregistrement existant, comme lorsque nous changeons d’adresse en mettant à jour notre profil de compte. Avec POST demander la création d’un profil supplémentaire, avec un PUT, le profil existant peut être remplacé, mais en utilisant la variable PATCH nous mettons simplement à jour la partie appropriée de l'enregistrement existant, comme notre adresse.

DELETE

La variable DELETE la méthode de requête supprime une ressource spécifiée dans la requête, comme si nous cliquions sur un lien pour supprimer entièrement notre profil de compte.

Il existe plusieurs autres méthodes, mais il s’agit de la liste des méthodes les plus courantes lorsque vous utilisez des API.

Exemple de requête

Maintenant que vous disposez des termes, concepts et étapes de base impliqués dans les API, nous pouvons consulter un exemple de requête d’API en pratique.

La page de notre exemple de navigateur comporte une URL de https://business.adobe.com/products/experience-platform/adobe-experience-platform.html. Lorsque l’utilisateur clique sur le lien Adobe Experience Platform, le navigateur effectue une GET demande pour cette page. Puisque nous avons le navigateur pour effectuer le travail pour nous, il nous suffit de cliquer sur , mais si un programmeur souhaite que cette demande se produise dans une application logicielle, il doit fournir tous les détails nécessaires pour que la demande d’API soit satisfaite.

Voici à quoi cela peut ressembler dans le code :

fetch(
  "https://business.adobe.com/products/experience-platform/adobe-experience-platform.html",
  {
    headers: {
      accept:
        "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
      "accept-language": "en-US,en;q=0.9",
      "sec-ch-ua":
        '" Not A;Brand";v="99", "Chromium";v="101", "Microsoft Edge";v="101"',
      "sec-fetch-dest": "document",
      "sec-fetch-mode": "navigate",
      "sec-fetch-site": "none",
      "sec-fetch-user": "?1",
      "upgrade-insecure-requests": "1",
    },
    referrerPolicy: "strict-origin-when-cross-origin",
    body: null,
    method: "GET",
    mode: "cors",
    credentials: "include",
  }
);

Dans le code ci-dessus, vous pouvez voir le URL le navigateur demande et, en bas de l’écran, le method: "GET" méthode de requête. Les autres lignes de code font également partie de la requête, mais ne sont pas incluses dans cet article.

Sur cette page