Un combo gagnant pour la lecture de données publiques – Real Python

SOAP vs REST vs GraphQL

Même si certains des exemples mentionnés ci-dessus sont axés sur les nouvelles plates-formes ou applications, les API Web existent depuis assez longtemps. À la fin des années 1990 et au début des années 2000, deux modèles de conception différents sont devenus la norme pour exposer publiquement les données:

1. SOAP (Simple Object Access Protocol) est généralement associé au monde de l'entreprise, a une utilisation plus stricte basée sur des contrats et est principalement conçu autour d'actions.
2. REST (transfert d'état de représentation) est généralement utilisé pour les API publiques et est idéal pour récupérer des données sur le Web. Il est beaucoup plus léger et plus proche de la spécification HTTP que SOAP.

De nos jours, il y a un petit nouveau en ville: GraphQL. Créé par Facebook, GraphQL est un langage de requête très flexible pour les API, dans lequel les clients décident exactement ce qu'ils veulent récupérer sur le serveur au lieu que le serveur décide quoi envoyer.

Si vous souhaitez en savoir plus sur les différences entre ces trois modèles de conception, voici quelques bonnes ressources:

Même si GraphQL est en hausse et est adopté par des entreprises de plus en plus grandes, y compris GitHub et Shopify, la vérité est que la majorité des API publiques sont toujours des API REST. Par conséquent, dans le cadre de ce didacticiel, vous ne découvrirez que les API REST et comment les utiliser à l'aide de Python.

demandes et API: un match fait au paradis

Lorsque vous utilisez des API avec Python, vous n'avez besoin que d'une seule bibliothèque: demandes. Avec lui, vous devriez être en mesure d'effectuer la plupart, sinon la totalité, des actions requises pour consommer n'importe quelle API publique.

Vous pouvez installer demandes en exécutant la commande suivante dans votre console:

$ demandes d'installation python -m pip

Pour suivre les exemples de code de ce didacticiel, assurez-vous que vous utilisez Python 3.8.1 et demandes 2.24.0 ou supérieur.

Points finaux et ressources

Comme vous l'avez vu ci-dessus, la première chose que vous devez savoir pour consommer une API est l'URL de l'API, généralement appelée URL de base. La structure de l'URL de base n'est pas différente des URL que vous utilisez pour naviguer sur Google, YouTube ou Facebook, bien qu'elle contienne généralement le mot api. Ce n'est pas obligatoire, mais plutôt une règle empirique.

Par exemple, voici les URL de base de quelques lecteurs d'API bien connus:

• https://api.twitter.com
• https://api.github.com
• https://api.stripe.com

Comme vous pouvez le voir, tout ce qui précède commence par https: // api et inclure le domaine officiel restant, tel que .twitter.com ou .github.com. Il n’existe pas de norme spécifique concernant l’aspect de l’URL de base de l’API, mais il est assez courant qu’elle imite cette structure.

Si vous essayez d'ouvrir l'un des liens ci-dessus, vous remarquerez que la plupart d'entre eux renverront une erreur ou vous demanderont des informations d'identification. En effet, les API nécessitent parfois des étapes d'authentification avant de pouvoir les utiliser. Vous en apprendrez plus à ce sujet un peu plus tard dans le didacticiel.

Ensuite, à l'aide de TheDogAPI qui vient d'être introduit, vous allez essayer de faire une requête de base pour voir en quoi elle peut différer de l'API Random User Generator que vous avez essayée ci-dessus:

>>> importer demandes
>>> réponse = demandes.obtenir("https://api.thedogapi.com/")
>>> réponse.texte
'"message": "L'API Dog"'

Dans ce cas, lors de l'appel de l'URL de base, vous obtenez ce message générique disant L'API Dog. En effet, vous appelez l'URL de base, qui est généralement utilisée pour des informations très basiques sur une API, et non pour les données réelles.

Appeler uniquement l'URL de base n'est pas très amusant, mais c'est là que les points de terminaison sont utiles. Une point final fait partie de l'URL qui spécifie ce Ressource vous voulez aller chercher. Les API bien documentées contiennent généralement un Référence API, ce qui est extrêmement utile pour connaître les points de terminaison et les ressources exacts d'une API et comment les utiliser.

Vous pouvez consulter la documentation officielle pour en savoir plus sur l'utilisation de TheDogAPI et sur les points de terminaison disponibles. Là-dedans, vous trouverez un / races point de terminaison que vous pouvez utiliser pour récupérer toutes les ressources ou objets de race disponibles.

Si vous faites défiler vers le bas, vous trouverez la section Envoyer une demande de test, où vous verrez un formulaire comme celui-ci:

C'est quelque chose que vous verrez dans de nombreuses documentations sur l'API: un moyen pour vous de tester rapidement l'API directement à partir de la page de documentation. Dans ce cas, vous pouvez cliquer sur Envoyer pour obtenir rapidement le résultat de l'appel de ce point de terminaison. Et voilà, vous venez d'appeler une API sans avoir à écrire de code pour celle-ci.

Maintenant, essayez-le dans le code localement en utilisant le point de terminaison des races et certaines des connaissances API que vous avez déjà:

>>> réponse = demandes.obtenir("https://api.thedogapi.com/v1/breeds")
>>> réponse.texte
'["weight":"imperial":"6 - 13","metric":"3 - 6","height": ...]'

Voilà, votre première liste de races en utilisant l'API de chien!

Si vous êtes un chat, ne vous inquiétez pas. Il existe également une API pour vous, avec le même point de terminaison mais une URL de base différente:

>>> réponse = demandes.obtenir("https://api.thecatapi.com/v1/breeds")
>>> réponse.texte
'[..."id":"abys","name":"Abyssinian"]'

Je parie que vous réfléchissez déjà à différentes façons d’utiliser ces API pour créer un joli projet parallèle, et c’est ce qui est formidable avec les API. Une fois que vous commencez à les utiliser, rien ne vous empêche de transformer un passe-temps ou une passion en un petit projet amusant.

Avant d'aller de l'avant, une chose que vous devez savoir sur les points de terminaison est la différence entre http: // et https: //. En un mot, HTTPS est la version cryptée de HTTP, rendant tout le trafic entre le client et le serveur beaucoup plus sûr. Lorsque vous utilisez des API publiques, vous devez absolument éviter d'envoyer des informations privées ou sensibles à http: // points de terminaison et n'utilisez que les API qui fournissent un https: // URL de base.

Pour plus d'informations sur les raisons pour lesquelles il est important de s'en tenir à HTTPS lors de la navigation en ligne, consultez Explorer HTTPS avec Python.

Dans la section suivante, vous approfondirez un peu plus les principaux composants d'un appel API.

Demande et réponse

Comme vous l'avez très brièvement lu ci-dessus, toutes les interactions entre un client – dans ce cas votre console Python – et une API sont divisées en une requête et une réponse:

• Demandes contiennent des données pertinentes concernant votre appel de demande d'API, telles que l'URL de base, le point de terminaison, la méthode utilisée, les en-têtes, etc.
• Réponses contiennent des données pertinentes renvoyées par le serveur, y compris les données ou le contenu, le code d'état et les en-têtes.

En utilisant à nouveau TheDogAPI, vous pouvez explorer un peu plus ce qui se trouve exactement à l'intérieur du Demander et Réponse objets:

>>> réponse = demandes.obtenir("https://api.thedogapi.com/v1/breeds")
>>> réponse

>>> réponse.demander


>>> demander = réponse.demander
>>> demander.URL
«https://api.thedogapi.com/v1/breeds»
>>> demander.chemin_url
'/ v1 / races'
>>> demander.méthode
'OBTENIR'
>>> demander.en-têtes
'User-Agent': 'python-requests / 2.24.0', 'Accept-Encoding': 'gzip, deflate',
'Accepter': '* / *', 'Connexion': 'keep-alive'

>>> réponse

>>> réponse.texte
'[{"poids":"impérial":"6-13""métrique":"3-6"[{"poids":"impérial":"6-13""métrique":"3-6"[{"weight":"imperial":"6-13""metric":"3-6"["weight":"imperial":"6-13""metric":"3-6"
"height": "imperial": "9 - 11.5", "metric": "23 - 29", "id": 1,
"nom": "Affenpinscher", ...]'
>>> réponse.status_code
200
>>> réponse.en-têtes
'Cache-Control': 'post-check = 0, pre-check = 0', 'Content-Encoding': 'gzip',
'Content-Type': 'application / json; jeu de caractères = utf-8 ',
'Date': 'Sam, 25 juillet 2020 17:23:53 GMT' ...

L'exemple ci-dessus vous montre quelques-uns des attributs les plus importants disponibles pour Demander et Réponse objets.

Vous en apprendrez plus sur certains de ces attributs dans ce didacticiel, mais si vous voulez creuser encore plus, vous pouvez consulter la documentation de Mozilla sur les messages HTTP pour une explication plus approfondie de chaque attribut.

Codes d'état

Les codes d'état sont l'une des informations les plus importantes à rechercher dans toute réponse d'API. Ils vous indiquent si votre demande a abouti, s’il manque des données, s’il manque des identifiants, etc.

Avec le temps, vous reconnaîtrez les différents codes d'état sans aide. Mais pour l'instant, voici une liste de certains des codes d'état les plus courants que vous trouverez:

Vous avez vu 200 OK plus tôt dans les exemples que vous avez exécutés, et vous pourriez même reconnaître 404 introuvable de naviguer sur le Web.

Vous pouvez vérifier l'état d'une réponse à l'aide de .status_code et .raison. Le demandes bibliothèque imprime également le code d'état dans la représentation de Réponse objet:

>>> réponse = demandes.obtenir("https://api.thedogapi.com/v1/breeds")
>>> réponse

>>> réponse.status_code
200
>>> réponse.raison
'D'ACCORD'

La demande ci-dessus renvoie 200, vous pouvez donc la considérer comme une demande réussie. Mais maintenant, jetez un œil à une demande échouante déclenchée lorsque vous incluez une faute de frappe dans le point de terminaison / racez:

>>> réponse = demandes.obtenir("https://api.thedogapi.com/v1/breedz")
>>> réponse

>>> réponse.status_code
404
>>> réponse.raison
'Pas trouvé'

Comme vous pouvez le voir, le / racez Le point de terminaison n'existe pas, donc l'API renvoie un 404 introuvable code d'état.

Vous pouvez utiliser ces codes d'état pour voir rapidement si votre demande doit être modifiée ou si vous devez vérifier à nouveau la documentation pour des fautes de frappe ou des pièces manquantes.

Contenu de la réponse

Comme vous venez de l'apprendre, le type de contenu que vous trouverez dans la réponse de l'API variera en fonction de la Type de contenu entête. Pour lire correctement le contenu de la réponse en fonction des différents Type de contenu en-têtes, le demandes le paquet est livré avec un couple de Réponse attributs que vous pouvez utiliser pour manipuler les données de réponse:

• .texte renvoie le contenu de la réponse au format Unicode.
• .teneur renvoie le contenu de la réponse en octets.

Vous avez déjà utilisé le .texte attribut ci-dessus. Mais pour certains types de données spécifiques, comme les images et autres données non textuelles, en utilisant .teneur est généralement une meilleure approche, même si elle renvoie un résultat très similaire à .texte:

>>> réponse = demandes.obtenir("https://api.thedogapi.com/v1/breeds/1")
>>> réponse.en-têtes.obtenir("Content-Type")
'application / json; jeu de caractères = utf-8 '
>>> réponse.teneur
b '{"poids": "impérial": "6 - 13", "métrique": "3 - 6" ...'

Comme vous pouvez le voir, il n'y a pas de grande différence entre .teneur et le précédemment utilisé .texte.

Cependant, en regardant la réponse Type de contenu en-tête, vous pouvez voir que le contenu est application / json;, un objet JSON. Pour ce type de contenu, le demandes bibliothèque comprend un .json () méthode que vous pouvez utiliser pour convertir immédiatement la réponse des octets de l'API en une structure de données Python:

>>> réponse = demandes.obtenir("https://api.thedogapi.com/v1/breeds/1")
>>> réponse.en-têtes.obtenir("Content-Type")
'application / json; jeu de caractères = utf-8 '
>>> réponse.json()
'poids': 'impérial': '6 - 13', 'métrique': '3 - 6',
'height': 'imperial': '9 - 11.5', 'metric': '23 - 29 '
...
>>> réponse.json()[[[["Nom"]
«Affenpinscher»

Comme vous pouvez le voir, après l'exécution response.json (), vous obtenez un dictionnaire que vous pouvez utiliser comme tout autre dictionnaire en Python.

Maintenant, en regardant l'exemple récent que vous avez exécuté à l'aide de l'API PlaceGOAT, essayez de récupérer cette même image de chèvre et jetez un œil à son contenu:

>>> réponse = demandes.obtenir("http://placegoat.com/200/200")
>>> réponse

>>> réponse.en-têtes.obtenir("Content-Type")
'image / jpeg'
>>> réponse.teneur
b ' xff  xd8  xff  xe0  x00  x10JFIF  x00  x01  x01  x01  x00H  ...'

Dans ce cas, parce que vous demandez une image, .teneur n'est pas très utile. En fait, c’est presque impossible à comprendre. Cependant, vous savez qu'il s'agit d'une image JPEG, vous pouvez donc essayer de la stocker dans un fichier et voir ce qui se passe:

>>> réponse = demandes.obtenir("http://placegoat.com/200/200")
>>> réponse

>>> réponse.en-têtes.obtenir("Content-Type")
'image / jpeg'
>>> déposer = ouvert("goat.jpeg", "wb")
>>> déposer.écrivez(réponse.teneur)
>>> déposer.Fermer()

Maintenant, si vous ouvrez le dossier dans lequel vous travaillez, vous trouverez un chèvre.jpeg fichier, qui est une image aléatoire d'une chèvre que vous venez de récupérer à l'aide d'une API. N'est-ce pas étonnant?

Méthodes HTTP

Lors de l'appel d'une API, il existe plusieurs méthodes différentes, également appelées verbes, que vous pouvez utiliser pour spécifier l'action que vous souhaitez exécuter. Par exemple, si vous vouliez récupérer des données, vous utiliseriez la méthode OBTENIR, et si vous vouliez créer des données, vous utiliseriez la méthode PUBLIER.

Lorsque vous consommez uniquement des données à l'aide d'API, vous vous en tenez généralement à OBTENIR requêtes, mais voici une liste des méthodes les plus courantes et leur cas d'utilisation typique:

Ces quatre méthodes sont généralement appelées Opérations CRUD comme ils vous permettent de ccréer, read, update et résupprimer les ressources.

Si vous êtes curieux de connaître les méthodes HTTP restantes, ou si vous souhaitez simplement en savoir un peu plus sur celles déjà mentionnées, consultez la documentation de Mozilla.

Jusqu'à présent, vous n'avez utilisé que .obtenir() pour récupérer des données, mais vous pouvez utiliser le demandes package pour toutes les autres méthodes HTTP également:

>>> demandes.Publier("https://api.thedogapi.com/v1/breeds/1")
>>> demandes.obtenir("https://api.thedogapi.com/v1/breeds/1")
>>> demandes.mettre("https://api.thedogapi.com/v1/breeds/1")
>>> demandes.effacer("https://api.thedogapi.com/v1/breeds/1")

Si vous essayez ces derniers sur votre console, vous remarquerez que la plupart d’entre eux renverront un Méthode 405 non autorisée code d'état. En effet, tous les points de terminaison ne permettront pas PUBLIER, METTRE, ou EFFACER méthodes. Surtout lorsque vous lisez des données à l'aide d'API publiques, vous constaterez que la plupart des API n'autorisent que OBTENIR demandes, car vous n’êtes pas autorisé à créer ou à modifier les données existantes.

Paramètres de requête

Parfois, lorsque vous appelez une API, vous obtenez une tonne de données dont vous n'avez pas besoin ou dont vous n'avez pas besoin. Par exemple, lors de l'appel de TheDogAPI / races endpoint, vous obtenez beaucoup d'informations sur une race donnée. Mais dans certains cas, vous voudrez peut-être extraire uniquement certaines informations sur une race donnée. C’est là que les paramètres de requête entrent en jeu!

Vous avez peut-être vu ou utilisé des paramètres de requête lors de la navigation en ligne. Par exemple, lorsque vous regardez une vidéo YouTube, vous avez une URL telle que https://www.youtube.com/watch?v=aL5GK2LVMWI. Le v = dans l'URL est ce que vous appelez un paramètre de requête. Il vient généralement après l'URL de base et le point de terminaison.

Pour ajouter un paramètre de requête à une URL donnée, vous devez ajouter un point d'interrogation (?) avant le premier paramètre de requête. Si vous souhaitez avoir plusieurs paramètres de requête dans votre demande, vous pouvez les séparer par une esperluette (&).

La même URL YouTube ci-dessus avec plusieurs paramètres de requête ressemblerait à ceci: https://www.youtube.com/watch?v=aL5GK2LVMWI&t=75.

Dans le monde des API, les paramètres de requête sont utilisés comme filtres que vous pouvez envoyer avec votre requête API pour affiner davantage les réponses. Par exemple, en revenant à l'API Random User Generator, vous savez comment générer un utilisateur aléatoire:

>>> demandes.obtenir("https://randomuser.me/api/").json()
{'résultats':[{'gender':'male''name':[{'gender':'male''name':[{'gender':'male''name':[{'gender':'male''name':
'title': 'Mr', 'first': 'Silvijn', 'last': 'Van Bekkum',
'location': 'street': 'number': 2480, 'name': 'Hooijengastrjitte',
'ville': 'Terherne', 'état': 'Drenthe',
'country': 'Pays-Bas', 'code postal': 59904 ...

Cependant, disons que vous souhaitez spécifiquement générer uniquement des utilisateurs féminins aléatoires. Selon la documentation, vous pouvez utiliser le paramètre de requête sexe = pour ça:

>>> demandes.obtenir("https://randomuser.me/api/?gender=female").json()
{'résultats':[{'gender':'female''name':[{'gender':'female''name':[{'gender':'female''name':[{'gender':'female''name':
'title': 'Mrs', 'first': 'Marjoleine', 'last': 'Van Huffelen',
'location': 'street': 'number': 8993, 'name': 'De Teebus',
'ville': 'West-Terschelling', 'état': 'Limbourg',
'country': 'Pays-Bas', 'code postal': 24241 ...

C'est super! Supposons maintenant que vous souhaitiez générer uniquement des femmes en provenance d'Allemagne. Encore une fois, en parcourant la documentation, vous trouvez une section sur la nationalité et vous pouvez utiliser le paramètre de requête nat = pour ça:

>>> demandes.obtenir("https://randomuser.me/api/?gender=female&nat=de").json()
{'résultats':[{'gender':'female''name':[{'gender':'female''name':[{'gender':'female''name':[{'gender':'female''name':
'title': 'Ms', 'first': 'Marita', 'last': 'Hertwig',
'location': 'street': 'number': 1430, 'name': 'Waldstraße',
'ville': 'Velden', 'état': 'Rheinland-Pfalz',
'pays': 'Allemagne', 'code postal': 30737 ...

À l'aide des paramètres de requête, vous pouvez commencer à récupérer des données plus spécifiques à partir d'une API, ce qui rend l'ensemble de l'expérience un peu plus adapté à vos besoins.

Pour éviter d'avoir à reconstruire l'URL encore et encore, vous pouvez utiliser le paramètres attribut à envoyer dans un dictionnaire de tous les paramètres de requête à ajouter à une URL:

>>> query_params = "le genre": "Femme", "nat": "de"
>>> demandes.obtenir("https://randomuser.me/api/", paramètres=query_params).json()
{'résultats':[{'gender':'female''name':[{'gender':'female''name':[{'gender':'female''name':[{'gender':'female''name':
'title': 'Ms', 'first': 'Janet', 'last': 'Weyer',
'location': 'street': 'number': 2582, 'name': 'Meisenweg',
'ville': 'Garding', 'état': 'Mecklenburg-Vorpommern',
'pays': 'Allemagne', 'code postal': 56953 ...

Vous pouvez appliquer ce qui précède à toute autre API de votre choix. Si vous revenez à TheDogAPI, la documentation vous permet de filtrer le point de terminaison des races pour ne renvoyer que les races qui correspondent à un nom spécifique. Par exemple, si vous souhaitez rechercher la race Labradoodle, vous pouvez le faire avec le paramètre de requête q:

>>> query_params = "q": "labradoodle"
>>> point final = "https://api.thedogapi.com/v1/breeds/search"
>>> demandes.obtenir(point final, paramètres=query_params).json()
[{'poids':'impérial':'45-100''métrique':'20-45'[{'poids':'impérial':'45-100''métrique':'20-45'[{'weight':'imperial':'45-100''metric':'20-45'['weight':'imperial':'45-100''metric':'20-45'
'height': 'imperial': '14 - 24 ',' metric ': '36 - 61',
'id': 148, 'nom': 'Labradoodle', 'race_group': 'Mixte' ...]

Voilà! En envoyant le paramètre de requête q avec la valeur labradoodle, vous pouvez filtrer toutes les races qui correspondent à cette valeur spécifique.

À l'aide des paramètres de requête, vous pouvez affiner davantage vos demandes et spécifier exactement ce que vous recherchez. La plupart des API que vous trouverez en ligne ont une sorte de paramètres de requête que vous pouvez utiliser pour filtrer les données. N'oubliez pas de parcourir la documentation et la référence API pour les trouver.

Authentification

L'authentification API est peut-être le sujet le plus complexe couvert dans ce didacticiel. Même si de nombreuses API publiques sont gratuites et entièrement publiques, un nombre encore plus important d'API sont disponibles derrière une forme d'authentification. Il existe de nombreuses API qui nécessitent une authentification, mais voici quelques bons exemples:

Les approches d'authentification vont des plus simples et directes, comme celles utilisant des clés API ou l'authentification de base, à des techniques beaucoup plus complexes et plus sûres, comme OAuth.

En règle générale, appeler une API sans informations d'identification ou avec les mauvaises renvoie un 401 Non autorisé ou 403 Interdit code d'état.

Clés API

Le niveau d'authentification le plus courant est le Clé API. Ces clés sont utilisées pour vous identifier en tant qu'utilisateur ou client de l'API et pour suivre votre utilisation de l'API. Les clés API sont généralement envoyées sous forme d'en-tête de demande ou de paramètre de requête.

Pour cet exemple, vous allez essayer l'API Mars Rover Photo de la NASA et récupérer des photos prises le 1er juillet 2020. À des fins de test, vous pouvez utiliser le DEMO_KEY Clé API fournie par défaut par la NASA. Sinon, vous pouvez rapidement générer le vôtre en accédant à la page API principale de la NASA et en cliquant Commencer.

Vous pouvez ajouter la clé API à votre demande en ajoutant le api_key = paramètre de requête:

>>>

>>> point final = "https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos"
>>> # Remplacez DEMO_KEY ci-dessous par votre propre clé si vous en avez généré une.
>>> clé API = "DEMO_KEY"
>>> query_params = "clé API": clé API, "earth_date": "2020-07-01"
>>> réponse = demandes.obtenir(point final, paramètres=query_params)
>>> réponse

Jusqu'ici tout va bien. Vous avez réussi à faire une demande authentifiée à l'API de la NASA et à récupérer un 200 OK réponse.

Jetez maintenant un œil à Réponse objet et essayez d'en extraire quelques images:

>>>

>>> réponse.json()
{'Photos':[{'id':754118[{'id':754118['id':754118['id':754118
            «sol»: 2809,
            'camera': 'id': 20,
                'nom': 'FHAZ',
                'rover_id': 5,
                'full_name': 'Caméra de prévention des risques avant',
            'img_src': 'https://mars.nasa.gov/msl-raw-images/...JPG',
            'earth_date': '01/07/2020',
            'rover': 'id': 5,
                'name': 'Curiosité',
                'landing_date': '2012-08-06',
                'launch_date': '2011-11-26',
                'status': 'actif',
        ...

>>> Photos = réponse.json()[[[["Photos"]
>>> impression(F"A trouvé len(Photos)    Photos")
Trouvé 12 photos
>>> Photos[[[[4][[[["img_src"]
«https://mars.nasa.gov/msl-raw-images/proj/msl/redops/ods/surface/sol/02809/opgs/edr/rcam/RRB_646869036EDR_F0810628RHAZ00337M_.JPG»

Utilisant .json () pour convertir la réponse dans un dictionnaire Python, puis récupérer le Photos champ de la réponse, vous pouvez parcourir tous les photo objets et même récupérer l'URL d'image d'une photo spécifique. Si vous ouvrez cette URL dans votre navigateur, vous verrez la photo suivante de Mars prise par l'un des rovers martiens:

Pour cet exemple, vous avez choisi un earth_date (01/07/2020) puis une photo spécifique du dictionnaire de réponses (4). Avant d'aller de l'avant, essayez de changer la date ou de récupérer des photos à partir d'un autre appareil photo pour voir comment cela change le résultat final.

OAuth: Premiers pas

Une autre norme très courante dans l'authentification API est OAuth. Vous n’apprendrez que les bases d’OAuth dans ce didacticiel, car il s’agit d’un sujet très vaste.

Même si vous ne saviez pas qu'il faisait partie d'OAuth, vous avez peut-être vu et utilisé le flux OAuth plusieurs fois. Chaque fois qu'une application ou une plateforme a un Connectez-vous avec ou Continue avec option, c'est le point de départ d'un flux OAuth:

Voici une description étape par étape de ce qui se passera si vous cliquez sur Continuer avec Facebook:

1. L'application Spotify demandera à l'API Facebook de démarrer un flux d'authentification. Pour ce faire, l'application Spotify enverra son ID d'application (identité du client) et une URL (redirect_uri) pour rediriger l'utilisateur après un succès ou une erreur.

2. Vous serez redirigé vers le site Web Facebook et invité à vous connecter avec vos identifiants. L'application Spotify ne verra ni n'aura accès à ces informations d'identification. C'est l'avantage le plus important d'OAuth.

3. Facebook vous montrera toutes les données que l'application Spotify demande à votre profil et vous demandera d'accepter ou de refuser le partage de ces données.

4. Si vous acceptez de donner à Spotify l'accès à vos données, vous serez redirigé vers l'application Spotify, déjà connecté.

When going through step 4, Facebook will provide Spotify with a special credential (access_token) that can be used repeatedly to fetch your information. This specific Facebook login token is valid for sixty days, but other apps might have different expiration periods. If you’re curious, then Facebook has a settings page that you can check to see which apps have been given your Facebook access token.

Now, from a more technical standpoint, here are the things you need to know when consuming APIs using OAuth:

• You need to create an application that will have an ID (app_id ou client_id) and a secret (app_secret ou client_secret).
• You need to have a redirect URL (redirect_uri), which the API will use to send information to you.
• You’ll get a code as the result of the authentication, which you need to exchange for an access token.

There are a few variations to the above, but generally speaking, most OAuth flows will have steps similar to these.

Tip: When you’re just testing things out and you need some sort of redirect URL to get a code, you can use a service called httpbin.

More specifically, you can use https://httpbin.org/anything as a redirect URL, as it’ll simply output whatever it gets as an input. You can test it yourself by navigating to that URL.

Next, you’ll dive into an example using the GitHub API!

import requests

# REPLACE the following variables with your Client ID and Client Secret
CLIENT_ID = ""
CLIENT_SECRET = ""

# REPLACE the following variable with what you added in the
# "Authorization callback URL" field
REDIRECT_URI = ""

def create_oauth_link():
    params = 
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "scope": "user",
        "response_type": "code",
    

    endpoint = "https://github.com/login/oauth/authorize"
    response = requests.obtenir(endpoint, params=params)
    url = response.url
    return url

def exchange_code_for_access_token(code=None):
    params = 
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "redirect_uri": REDIRECT_URI,
        "code": code,
    

    headers = "Accept": "application/json"
    endpoint = "https://github.com/login/oauth/access_token"
    response = requests.post(endpoint, params=params, headers=headers).json()
    return response[[[["access_token"]

link = create_oauth_link()
impression(f"Follow the link to start the authentication with GitHub: link")
code = input("GitHub code: ")
access_token = exchange_code_for_access_token(code)
impression(f"Exchanged code code    with access token: access_token")

def print_user_info(access_token=None):
    headers = "Authorization": f"token access_token"
    endpoint = "https://api.github.com/user"
    response = requests.obtenir(endpoint, headers=headers).json()
    name = response[[[["name"]
    username = response[[[["login"]
    private_repos_count = response[[[["total_private_repos"]
    impression(
        f"name    (username) | private repositories: private_repos_count"
    )

    1import requests
    2
    3# REPLACE the following variables with your Client ID and Client Secret
    4CLIENT_ID = ""
    5CLIENT_SECRET = ""
    6
    7# REPLACE the following variable with what you added in
    8# the "Authorization callback URL" field
    9REDIRECT_URI = ""
dix
11def create_oauth_link():
12    params = 
13        "client_id": CLIENT_ID,
14        "redirect_uri": REDIRECT_URI,
15        "scope": "user",
16        "response_type": "code",
17    
18    endpoint = "https://github.com/login/oauth/authorize"
19    response = requests.obtenir(endpoint, params=params)
20    url = response.url
21    return url
22
23def exchange_code_for_access_token(code=None):
24    params = 
25        "client_id": CLIENT_ID,
26        "client_secret": CLIENT_SECRET,
27        "redirect_uri": REDIRECT_URI,
28        "code": code,
29    
30    headers = "Accept": "application/json"
31    endpoint = "https://github.com/login/oauth/access_token"
32    response = requests.post(endpoint, params=params, headers=headers).json()
33    return response[[[["access_token"]
34
35def print_user_info(access_token=None):
36    headers = "Authorization": f"token access_token"
37    endpoint = "https://api.github.com/user"
38    response = requests.obtenir(endpoint, headers=headers).json()
39    name = response[[[["name"]
40    username = response[[[["login"]
41    private_repos_count = response[[[["total_private_repos"]
42    impression(
43        f"name    (username) | private repositories: private_repos_count"
44    )
45
46link = create_oauth_link()
47impression(f"Follow the link to start the authentication with GitHub: link")
48code = input("GitHub code: ")
49access_token = exchange_code_for_access_token(code)
50impression(f"Exchanged code code    with access token: access_token")
51print_user_info(access_token=access_token)

$ John Doe (johndoe) | number of private repositories: 42

Rate Limiting

Given that APIs are public facing and can be used by anyone, people with bad intentions often try to abuse them. To prevent such attacks, you can use a technique called rate limiting, which restricts the number of requests that users can make in a given time frame.

Some APIs may actually block your IP or API keys if you go over the defined rate limit too often. Be careful not to exceed the limits set by the API developers. Otherwise, you might have to wait a while before calling that API again.

For the example below, you’ll once again use the GitHub API and the /events endpoint. According to its documentation, GitHub allows about sixty unauthenticated requests per hour. If you go above that, then you’ll get a 403 status code and won’t be able to make any more API calls for quite some time.

For the sake of demonstration, you’ll purposefully try to exceed GitHub’s rate limit to see what happens. In the code below, you’ll request data until you get a status code other than 200 OK:

>>> endpoint = "https://api.github.com/events"
>>> for i dans range(100):
>>>   response = requests.obtenir(endpoint)
>>>   impression(f"i    - response.status_code")
>>>   if response.status_code != 200:
>>>     break
0 - 200
1 - 200
2 - 200
3 - 200
4 - 200
5 - 200
...
55 - 200
56 - 200
57 - 403
>>> response

>>> response.json()
'message': "API rate limit exceeded for .",
    'documentation_url': 'https://developer.github.com/v3/#rate-limiting'

There you have it: After about sixty requests, the API stopped returning 200 OK responses and returned a 403 Forbidden response instead, informing you that you exceeded the API rate limit.

Some APIs, like GitHub’s, might even include additional information in the headers regarding your current rate limit and how many requests you have remaining. These are very helpful for you to avoid going over the defined limit. Have a look at the latest response.headers to see if you can find those specific rate limiting headers.

Searching and Fetching Trending GIFs

How about making a small script that fetches the top three trending GIFs from the GIPHY website? To do this, you need to create an app and get an API key from GIPHY. You can find instructions by expanding the box below, and you can also check GIPHY’s quickstart documentation.

Step 1: Create a GIPHY Account

You should start by creating a GIPHY account:

There’s nothing new here, just your typical email and password form, with an additional username field.

Step 2: Create an Application

After creating your GIPHY account, you can jump into the Developer Dashboard to see your existing applications:

In this case, you haven’t set up an application yet, so it looks a bit empty. You can create your first application by clicking Create an App:

Make sure to select the API version, not the SDK one. After that, you’ll be asked to fill in a few more details about your application:

You can see an example application name and description above, but feel free to fill these out as you prefer.

Step 3: Fetching the API Key

Once you’ve completed the steps above, you should get a new app in your Dashboard, below the Your Apps section. In there, you’ll have an API key like so:

Now you can copy and paste this API key into your code to make GIPHY API requests.

After you have the API key in your hands, you can start writing some code to consume this API. However, sometimes you want to run some tests before you implement a lot of code. I know I do. The thing is, a few APIs will actually provide you with tools to fetch API data directly from the documentation or their dashboard.

In this particular case, GIPHY provides you with an API Explorer that, after you create your app, allows you to start consuming the API without writing a line of code.

Some other APIs will provide you with explorers within the documentation itself, which is what TheDogAPI does on the bottom of each API reference page.

In any case, you can always use code to consume APIs, and that’s what you’ll do here. Grab the API key from the dashboard and, by replacing the value of the API_KEY variable below, you can start consuming the GIPHY API:

    1import requests
    2
    3# Replace the following with the API key generated.
    4API_KEY = "API_KEY"
    5endpoint = "https://api.giphy.com/v1/gifs/trending"
    6
    7params = "api_key": API_KEY, "limit": 3, "rating": "g"
    8response = requests.obtenir(ENDPOINT, params=params).json()
    9for gif dans response[[[["data"]:
dix    title = gif[[[["title"]
11    trending_date = gif[[[["trending_datetime"]
12    url = gif[[[["url"]
13    impression(f"title    | trending_date    | url")

At the top of the file, on lines 4 and 5, you define your API_KEY and the GIPHY API endpoint since they won’t change as often as the rest.

On line 7, making use of what you learned in the query parameters section, you define the params and add your own API key. You also include a couple of other filters: limit to get 3 results and rating to get only appropriate content.

Finally, after getting a response, you iterate through the results on line 9. For each GIF, you print its title, date, and URL on line 13.

Running this piece of code in the console would output a somewhat structured list of GIFs:

Excited Schitts Creek GIF by CBC | 2020-11-28 20:45:14 | https://giphy.com/gifs/cbc-schittscreek-schitts-creek-SiGg4zSmwmbafTYwpj
Saved By The Bell Shrug GIF by PeacockTV | 2020-11-28 20:30:15 | https://giphy.com/gifs/peacocktv-saved-by-the-bell-bayside-high-school-dZRjehRpivtJsNUxW9
Schitts Creek Thank You GIF by CBC | 2020-11-28 20:15:07 | https://giphy.com/gifs/cbc-funny-comedy-26n79l9afmfm1POjC

Now, let’s say you want to make a script that allows you to search for a specific word and fetch the first GIPHY match to that word. A different endpoint and slight variation of the code above can do that quite quickly:

import requests

# Replace the following with the API key generated.
API_KEY = "API_KEY"
endpoint = "https://api.giphy.com/v1/gifs/search"

search_term = "shrug"
params = "api_key": API_KEY, "limit": 1, "q": search_term, "rating": "g"
response = requests.obtenir(endpoint, params=params).json()
for gif dans response[[[["data"]:
    title = gif[[[["title"]
    url = gif[[[["url"]
    impression(f"title    | url")

There you have it! Now you can modify this script to your liking and generate GIFs on demand. Try fetching GIFs from your favorite show or movie, adding a shortcut to your terminal to get the most popular GIFs on demand, or integrating with another API from your favorite messaging system—WhatsApp, Slack, you name it. Then start sending GIFs to your friends and coworkers!

Getting COVID-19 Confirmed Cases Per Country

Even though this may be something that you’re tired of hearing about by now, there’s a free API with up-to-date world COVID-19 data. This API doesn’t require authentication, so it’s pretty straightforward to get some data right away. The free version that you’ll use below has a rate limit and some restrictions on the data, but it’s more than enough for small use cases.

For this example, you’ll get the total number of confirmed cases up to the previous day. I randomly picked Germany again as the country, but you can pick any country slug you like:

    1import requests
    2from datetime import date, timedelta
    3
    4today = date.today()
    5yesterday = today - timedelta(days=1)
    6country = "germany"
    7endpoint = f"https://api.covid19api.com/country/country/status/confirmed"
    8params = "from": str(yesterday), "to": str(today)
    9
dixresponse = requests.obtenir(endpoint, params=params).json()
11total_confirmed = 0
12for day dans response:
13    cases = day.obtenir("Cases", 0)
14    total_confirmed += cases
15
16impression(f"Total Confirmed Covid-19 cases in country: total_confirmed")

On lines 1 and 2, you import the necessary modules. In this case, you have to import the date et timedelta objects to be able to get today’s and yesterday’s dates.

On lines 6 to 8, you define the country slug you want to use, the endpoint, and the query parameters for the API request.

The response is a list of days, and for each day you have a Cases field that contains the total number of confirmed cases on that date. On line 11, you create a variable to keep the total number of confirmed cases, and then on line 14 you iterate through all the days and sum them up.

Printing the end result will show you the total number of confirmed cases in the selected country:

Total Confirmed Covid-19 cases in germany: 1038649

In this example, you’re looking at total number of confirmed cases for a whole country. However, you could also try looking at the documentation and fetching the data for your specific city instead. And why not make it a bit more thorough and get some other data, such as the number of recovered cases?

Searching Google Books

If you have a passion for books, then you might want a quick way to search for a specific book. You might even want to connect it to your local library’s search to see if a given book is available using the book’s ISBN.

For this example, you’ll use the Google Books API and the public volumes endpoint to do simple searches of books.

Here’s a straightforward piece of code to look for the words moby dick in the whole catalog:

    1import requests
    2
    3endpoint = "https://www.googleapis.com/books/v1/volumes"
    4query = "moby dick"
    5
    6params = "q": query, "maxResults": 3
    7response = requests.obtenir(endpoint, params=params).json()
    8for book dans response[[[["items"]:
    9    volume = book[[[["volumeInfo"]
dix    title = volume[[[["title"]
11    published = volume[[[["publishedDate"]
12    description = volume[[[["description"]
13    impression(f"title    (published) | description")

This code example is pretty similar to the ones you’ve seen before. You start on lines 3 and 4 by defining important variables, such as the endpoint and, in this case, the query.

After making the API request, on line 8 you start iterating through the results. Then, on line 13, you print the most interesting information for each book that matches your initial query:

Moby-Dick (2016-04-12) | "Call me Ishmael." So begins the famous opening...
Moby Dick (1892) | A literary classic that wasn't recognized for its...
Moby Dick; Or, The Whale (1983-08-16) | The story of Captain Ahab's...

You can print the book variable inside the loop to see what other fields you have available. Here are a few that could be useful for further improving this code:

• industryIdentifiers
• averageRating et ratingsCount
• imageLinks

A fun challenge to do with this API is to use your OAuth knowledge and create your own bookshelf app that keeps records of all the books you read or want to read. You can even connect it to your favorite bookstore or library afterward to quickly find books from your wish list that are available near you. This is just one idea—I’m sure you can come up with more.