JAMstack

Comment utiliser les API : une introduction simple avec tutoriels

Cet article est une adaptation de How to Use APIs: A Painless Introduction + Tutorials écrit à l'origine par Maxime Laboissonniere

Si vous travaillez même à distance dans l'industrie du développement Web, vous êtes sûr à 100% d'entendre ces trois lettres infâmes : API.

Elles sont prononcées par n00bs et experts :

"Pourquoi est-ce que je dois faire un appel d’API ? Est-ce qu'il y a un numéro ?"
"Un simple appel à cette API tierce fera l'affaire ici."
"Nous allons vous construire une API RESTful, en s'assurant que votre nouveau système fonctionne bien avec les autres services."

Alors que les API peuvent sembler intimidantes, elles peuvent littéralement changer votre vie de développeur.

Pourquoi ? Eh bien, apprendre à utiliser correctement les API peut simplifier, accélérer et renforcer votre flux de travail de développement. Construire ou intégrer des API apporte une part équitable des bénéfices pour les clients et pour vous-même.

En tant que développeurs, vous entendez souvent le conseil "ne réinventez pas la roue":

Blagues à part, les API jouent un rôle important dans le fait de ne pas réinventer la roue. La compréhension des bases des API est une compétence essentielle pour les développeurs web modernes. Dans ce post, nous vous aiderons à le faire. Nous couvrirons :

  • Les avantages de l'utilisation d'une API
  • Qu'est-ce qu'une API est réellement
  • Quelles sont les types d’API existantes
  • Cas d'utilisation pratique sur l'utilisation des API
    Alors c’est parti !

Les avantages de l’API : pourquoi les utiliser ?

why-use-api-benefits
Augmentez votre niveau de dev avec les APIs

L'un des premiers jalons de ma carrière en programmation consistait à bien comprendre les APIs.

Je les utilise tout le temps.

Avant d'entrer dans le vif du sujet, laissez-moi d'abord vous convaincre que la compréhension des APIs vaut bien votre temps.

Parce que l'apprentissage de l'utilisation des API augmente considérablement l'efficacité de votre développement.

Tout d'abord, il vous permet de tirer parti de la logique préexistante ou des parties que vous n'avez pas à écrire vous-même. Mêmes certaines choses que vous pourriez pas coder vous-même ! Donc, pour gagner du temp, il est essentiel en tant que développeur d'avoir une idée de ce à quoi ressemble une API.

Deuxièmement, de nombreux problèmes de développement que vous rencontrerez ont déjà été résolus par quelqu'un avant vous. Quelle que soit la forme prise par ces solutions existantes (FaaS, bibliothèques, services Web, SDK, API de contenu, etc.), vous aurez probablement besoin d'une API pour interagir avec elles.

Alors, que sont les API, exactement ?

what-are-apis-definition
API web, image de MS

Eh bien, la définition officielle et décourageante est la suivante :

En programmation informatique, une interface de programmation d'application (API) est un ensemble de définitions de sous-programmes, de protocoles et d'outils pour la construction de logiciels d'application. En termes généraux, il s'agit d'un ensemble de méthodes de communication clairement définies entre différents composants logiciels. Une bonne API facilite le développement d'un programme informatique en fournissant tous les blocs de construction, qui sont ensuite assemblés par le programmeur.

Un peu lourd, hein ? Prenons une définition un peu plus conviviale de l'API, fait maison :

Autrement dit, une API déclare une interface pour que vous puissiez interagir avec sa logique sans que vous ayez à savoir ce qui se passe sous le capot. Cette définition peut être appliquée à n'importe quel langage, protocole ou environnement dans lequel vous vous trouvez, aussi longtemps que cela se passe au niveau programmatique (plus de détails ci-dessous).

Pour mieux comprendre les API, indiquons ce qu'elles ne sont PAS :

  • Une API n'est pas nécessairement un service externe. Par exemple, vous pouvez inclure des bibliothèques directement dans votre solution OU les utiliser via une API.
  • Une API n'est pas seulement une interface. C'est à la fois la spécification / format et la mise en œuvre.
  • Une API n'est pas une interface graphique. Il ne fait pas d'interactions au niveau graphique ; il fonctionne uniquement sur la couche programmatique, soit par l'intermédiaire d'un langage de programmation, soit par un protocole de communication.

Différents types d'API

Toutes les API ne sont pas créées égales.

Même s'ils partagent pour la plupart le même but, certains l'atteignent bien mieux que d'autres. Comme il s'agit d'une intro en douceur, je ne vais pas plonger dans ce qui rend une API meilleure que d'autres. Cependant, gardez à l'esprit que les gens ont des approches très différentes pour créer des API. Si ce sujet vous intéresse, Recherchez sur Google les concepts de "modèles de conception d'API" et de "paradigmes d'API". Ou commencez simplement avec cet article d'entrée de gamme. :)

Objectifs

L'objectif des API est de faciliter votre vie de développeur. Comment font-ils cela ? En agrégeant les fonctionnalités / fonctions ensemble et en exposant ces fonctionnalités via des points de terminaison (généralement des modèles d'URL utilisés pour communiquer avec l'API). Ces points de terminaison sont la seule façon d'interagir avec n'importe quelle API. Chaque point de terminaison aura un format spécifié pour ses demandes et ses réponses. Vous trouverez généralement ce format dans la documentation de l'API.

Les points de terminaison peuvent être des fonctions simples ou composées de nombreuses fonctions qui appellent d'autres API, etc. Le seul point crucial ici est que la logique sous-jacente de ces fonctions est entièrement abstraite. Vous n'avez pas besoin de savoir ce qui se passe en eux pour les utiliser. Tant que vous utilisez le bon format, vous serez en mesure de les consommer, ce qui est une façon élégante de dire en utilisant certaines parties de votre application.

Enfin, une API est comme n'importe quelle interface : l'interrupteur allume la lumière, que vous sachiez comment les courants électriques fonctionnent ou pas (en tant que jeune adulte, j'ai aussi appris que vous devez payer la facture d'électricité pour le faire fonctionner, c'est une histoire différente.)

Comment utiliser les API : exemples pratiques

Appel d'API typique

Lire et comprendre une documentation d'API

Je ne veux pas m'étendre ici sur les explications conceptuelles. Analysons donc une API très simple pour la décortiquer et voir comment elle fonctionne dans un scénario réel. Nous prendrons l'objet natif JavaScript Math pour le faire (documentation disponible ici).

Vous pouvez voir dans les documents que chaque fonction de l'objet décrit ce que le format d'entrée doit être (nombre, tableau de nombres, etc.) et décrit le format de la sortie. Notez, cependant, comment rien n'est mentionné concernant la logique pour exécuter ces fonctions. Par exemple, si vous lancez votre console de développement et tapez Math.sqrt (sans exécuter la fonction), vous obtenez quelque chose comme ƒ sqrt () {[code natif]}. C'est l'esprit d'une API : que vous appeliez l'une de vos API de système d'exploitation ou une API Web, ces principes resteront.

Exemples de base de cas d'utilisation d'API

Il y a une tonne de choses à faire avec les fournisseurs d'API populaires. L'API Google Maps, par exemple, est souvent utilisée pour créer de meilleures expériences utilisateur avec des données basées sur la cartographie en temps réel et les signaux de trafic. L'API Twitter, une autre grande, peut être utilisée pour filtrer et afficher des Tweets ciblés en temps réel.

Maintenant, nous allons nous intéresser aux API basées sur le Web et nous allons plonger dans des cas d'utilisation spécifiques. Notez que nous utiliserons Postman dans nos exemples. Bien sûr, ce client est lié à un environnement Web, mais de tels outils existent également dans d'autres environnements. Il est intéressant de jeter un coup d'œil sur les outils fournis pour un environnement donné avant de commencer à jouer avec ; peut vous faire gagner beaucoup de temps.

Si vous voulez réaliser l'exemple avec nous, vous aurez besoin de télécharger le client Postman.

Consommer une API publique pour récupérer des données

Notre premier exemple va être assez simple, mais toujours plus intéressant que celui des mathématiques.

Nous allons utiliser l'API Dog ! Non seulement c'est une API amusante, mais elle ne nécessite aucune authentification. De plus, il s'agit d'une API HTTP REST, ce qui signifie qu'il s'agit d'une API Web. Comme il est lié à cet environnement, il nous oblige à nous conformer à certaines spécificités du protocole : dans ce cas, les verbes HTTP (GET, PUT, POST, DELETE, etc.). Pour notre exemple, nous allons garder les choses simples et utiliser uniquement le verbe GET. L'API n'autorise aucun autre support de toute façon. La plupart des API publiques vous permettent uniquement de consommer des données et de n'en poster aucune, donc le verbe GET.

Ouvrons Postman et voyons à quoi ressemble son interface.

Mon interface utilisateur utilise le thème sombre, donc il pourrait légèrement différer du vôtre.

Il y a peut-être beaucoup d'informations à digérer ici, alors commençons par le VERBE et l'URL.

Le verbe par défaut devrait être GET afin que vous puissiez le garder de cette façon et entrez l'URL suivante : https://dog.ceo/api/breeds/list/all

Cliquez sur "Send" et c'est parti ! Vous devriez recevoir une réponse avec les données appropriées. Voilà ! Vous venez de faire votre premier appel d'API. Maintenant, pour cet exemple, nous n'utiliserons aucune des données reçues. Mais vous avez l'idée : vous pouvez montrer différentes races de chiens à votre utilisateur et afficher une image d'une race donnée s'il clique dessus.

Vous pouvez jouer avec les différentes routes dans leur documentation pour vous familiariser avec l'environnement.

Fait intéressant : ce petit projet est également open source, vous pouvez donc jeter un oeil sous le capot ici.

Gestion de l'authentification avec une API privée

Vous devriez maintenant mieux comprendre comment différentes pièces fonctionnent ensemble quand il s'agit d'API. Alors faisons un tutoriel plus complexe qui inclut l'authentification. Je vais maintenant utiliser l'API de l'application Snipcart.

Ici, nous n'utiliserons que du code pour interagir avec l'API de Snipcart. Vous pouvez fermer Facteur, mais gardez-le à portée de main ; il est bon d'utiliser un tel outil lorsque vous démarrez avec une API.

L'objectif sera de créer un outil CLI simple pour créer des réductions à usage unique pour les acheteurs. Ces réductions seront générées via l'API, et tout cela se fera entièrement sur votre ordinateur.

Créez un nouveau dossier pour ce projet, utilisez npm init dans le dossier et démarrez votre éditeur de texte. Maintenant, créez un fichier index.js, puis ouvrez le fichier package.json. Dans celui-ci, ajoutez les lignes suivantes dans l'objet racine :

"bin": {
    "discounts": "./index.js"
}

Nous aurons aussi besoin du package commander pour analyser les entrées du client. Exécutez npm install --save commander dans le dossier actuel. Nous utiliserons également une petite librairie pour créer des identifiants. Vous pouvez l'installer avec npm install --save shortid. Pendant que nous y sommes, exécutons également npm install --save request pour nous faciliter les appels HTTP. Revenez dans votre fichier index.js et collez ce code :

#!/usr/bin/env node
var program = require('commander');
var shortid = require('shortid');
var request = require('request');

function CreateDiscount(){
    var discount = {
        name: '20% OFF',
        trigger: 'Code',
        type: 'Rate',
        rate: 20,
        maxNumberOfUsages: 1,
        code: shortid.generate()
    }

    request({
        url: "http://app.snipcart.com/api/discounts",
        auth: {
            'user': 'YOUR_API_KEY'
        },
        method: "POST",
        json: true,
        body: discount
    }, function (error, response, body){
        console.log(body.code);
    });
}

program
    .arguments('<number>')
    .action(function(number) {
        for(var i = parseFloat(number); i > 0; i--){
            CreateDiscount();
        }
    })
    .parse(process.argv);

Concentrons-nous ici sur la fonction request. C'est ici que nous appelons l'API externe à Snipcart. Vous pouvez voir que nous passons method : "POST" à la méthode. C'est parce que nous voulons publier des données sur l'API de Snipcart. En spécifiant cette méthode, l'API mappera l'action correctement afin qu'elle puisse lire le corps de la requête où se trouvent les données de remise.

Une fonctionnalité d'API passionnante que nous n'avions pas encore utilisée est l'authentification. Nos autres exemples étaient tous sur des API publiques : ils ne nécessitent aucune authentification. Mais dans les scénarios de la vie réelle, la plupart des API que vous utiliserez nécessiteront probablement une authentification, comme l'API Twitter ou l'API Google Maps, par exemple. C'est un "modèle" standard dans le monde de l'API. Nos clients ne seraient pas si heureux si nous laissions quiconque créer des réductions sur leur boutique. ;)

Les concepts d'authentification peuvent devenir très pénibles assez rapidement ; vous pouvez lire ce post intéressant pour mieux maîtriser le sujet.

Dans notre cas, nous transmettons la clé API directement dans la requête et le serveur nous reconnaît ! Il peut alors exécuter la requête limitée à notre compte.

Si vous voulez tester notre petite application, vous pouvez lancer npm install -g dans le répertoire du projet et simplement lancer discounts x pour créer des remises x nombre de fois. Vous pouvez aller dans votre tableau de bord Snipcart (comptes gratuits pour toujours en mode Test) et voir par vous-même que les réductions ont été créées correctement. Vous pouvez imaginer comment cela peut être puissant : si vous deviez créer 200 de ces réductions, cela demanderait beaucoup trop de temps pour le faire via notre interface utilisateur. Lorsque vous connaissez le fonctionnement des API, vous pouvez le faire en quelques minutes. Le code est également réutilisable, donc si vous devez faire la même chose dans un mois, eh bien, vous êtes déjà prêt !

Conclusion

J'espère sincèrement que ce manuel vous aidera à mieux comprendre ce que sont les API et comment les utiliser dans votre processus de développement.
Quelques rappels :

  • Les API vont accélérer votre vitesse et élargir votre portée de développement. Utilise les !
  • Les API ne sont PAS nécessairement liées à l'écosystème Web ; vous les verrez partout.
  • Vérifiez toujours la documentation de l'API que vous souhaitez utiliser.
  • Toujours rechercher des outils existants (API ou autres) dans votre écosystème avant de commencer à coder.
    Maintenant, notre dernier exemple n'est pas vraiment "prêt" à la production, mais il vous donne une bonne idée de la façon dont les choses pourraient ressembler dans un cas d'utilisation réel. Il y a beaucoup de choses que nous aurions pu améliorer, comme laisser l'utilisateur choisir le type de réduction, etc. Nous pourrions également utiliser les codes créés pour les envoyer par Email directement dans la même fonction au lieu de simplement les enregistrer. Si nous avions des besoins avancés pour nos outils de remises, nous aurions pu écrire une API nous-mêmes. De là, nous pourrions même créer une interface utilisateur qui interagirait avec notre API si nous le voulions. En tout cas, j'espère que vous avez l'idée maintenant ! :)

Alors, quelle est la prochaine étape ? Comme presque tout dans la sphère du développement, vous devrez coder, coder, coder et coder davantage ! C'est ainsi que vous vous familiariserez avec la gestion et l'intégration de l'API. Après un certain temps, vous deviendrez efficace avec eux.

Et c'est là que le vrai plaisir commence.

Author image

A propos de Maxime Chenot