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

By | février 22, 2021

Expert Python

Savoir comment consommer une API est l'une de ces compétences magiques qui, une fois maîtrisées, ouvriront un tout nouveau monde de possibilités, et consommer des API avec Python est un excellent moyen d'acquérir une telle compétence.

Un grand nombre d'applications et de systèmes que vous utilisez quotidiennement sont connectés à une API. Qu'il s'agisse de choses très simples et banales, comme vérifier la météo le matin, à des actions plus addictives et plus fastidieuses, telles que le défilement de votre flux Instagram, TikTok ou Twitter, les API jouent un rôle central.

À la fin de ce didacticiel, vous pourrez utiliser Python pour utiliser la plupart des API que vous rencontrez. Si vous êtes un développeur, savoir comment utiliser les API avec Python vous rendra beaucoup plus compétent, en particulier lorsqu'il s'agit d'intégrer votre travail avec des applications tierces.

Vous pouvez télécharger le code source des exemples que vous verrez dans ce didacticiel en cliquant sur le lien ci-dessous:

Se familiariser avec les API

API signifie Interface de programmation d'applications. Essentiellement, une API agit comme une couche de communication, ou comme son nom l'indique, une interface, qui permet à différents systèmes de se parler sans avoir à comprendre exactement ce que chacun fait.

Les API peuvent prendre de nombreuses formes ou formes. Il peut s'agir d'API de système d'exploitation, utilisées pour des actions telles que l'activation de votre caméra et l'audio pour rejoindre un appel Zoom. Ou il peut s'agir d'API Web, utilisées pour des actions axées sur le Web, comme aimer des images sur votre Instagram ou récupérer les derniers tweets.

Quel que soit le type, toutes les API fonctionnent généralement de la même manière. Vous faites généralement un demander pour des informations ou des données, et l'API renvoie un réponse avec ce que vous avez demandé. Par exemple, chaque fois que vous ouvrez Twitter ou que vous faites défiler votre flux Instagram, vous faites essentiellement une demande à l'API derrière cette application et obtenez une réponse en retour. Ceci est également connu comme appel une API.

Dans ce didacticiel, vous vous concentrerez davantage sur les API de haut niveau qui communiquent sur les réseaux, également appelées API Web.

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.

Appel de votre première API à l'aide de Python

Assez parlé, il est temps de passer votre premier appel API! Pour le premier exemple, vous allez appeler une API populaire pour générer des données utilisateur aléatoires.

Tout au long du didacticiel, vous verrez de nouvelles API introduites dans des blocs d'alerte comme celui ci-dessous. C'est un moyen pratique pour vous de faire défiler par la suite et de repérer rapidement toutes les nouvelles API que vous avez découvertes.

La seule chose dont vous avez besoin pour commencer avec l'API Random User Generator est de savoir avec quelle URL l'appeler. Pour cet exemple, l'URL à utiliser est https://randomuser.me/api/, et voici le plus petit appel d'API que vous puissiez effectuer:

>>>

>>> importer demandes
>>> demandes.obtenir("https://randomuser.me/api/")

Dans ce petit exemple, vous importez le demandes bibliothèque, puis récupérez (ou obtenez) des données à partir de l'URL de l'API Random User Generator. Mais vous ne voyez en fait aucune des données renvoyées. Ce que vous obtenez à la place est un Réponse [200], ce qui en termes d'API signifie que tout s'est bien passé.

Si vous voulez voir les données réelles, vous pouvez utiliser .texte du retour Réponse objet:

>>>

>>> importer demandes
>>> réponse = demandes.obtenir("https://randomuser.me/api/")
>>> réponse.texte
'{"résultats":[{"gender":"female"[{"gender":"female"[{"gender":"female"[{"gender":"female"
"name": "title": "Ms", "first": "Isobel", "last": "Wang" ... '

C'est tout! Ce sont les bases de la consommation des API. Vous avez réussi à récupérer votre premier utilisateur aléatoire de l'API Random User Generator en utilisant Python et le demandes bibliothèque.

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:

Consommer des API avec Python: exemple de documentation
Test d'API dans la documentation TheDogAPI

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:

Code d'état Description
200 OK Votre demande a été acceptée!
201 Créé Votre demande a été acceptée et la ressource a été créée.
400 Mauvaise demande Votre demande est erronée ou manque d'informations.
401 Non autorisé Votre demande nécessite des autorisations supplémentaires.
404 introuvable La ressource demandée n'existe pas.
Méthode 405 non autorisée Le point de terminaison n'autorise pas cette méthode HTTP spécifique.
Erreur de serveur interne 500 Votre demande n'était pas attendue et a probablement cassé quelque chose côté serveur.

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:

Méthode HTTP Description Méthode des demandes
PUBLIER Créez une nouvelle ressource. demandes.post ()
OBTENIR Lisez une ressource existante. demandes.get ()
METTRE Mettez à jour une ressource existante. demandes.put ()
EFFACER Supprimer une ressource existante. demandes.delete ()

Ces quatre méthodes sont généralement appelées Opérations CRUD comme ils vous permettent de ccréer, read, update et 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.

Apprentissage des concepts d'API avancés

Maintenant que vous avez une bonne compréhension des bases de la consommation d'API à l'aide de Python, il y a quelques sujets plus avancés qui méritent d'être abordés, même brièvement, tels que l'authentification, la pagination et la limitation de débit.

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:

Consommer des API avec Python: Mars Rover Picture
Image de l'API Mars Rover

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:

Consommation d'API avec Python: exemple de connexion OAuth
Exemples de boutons de connexion OAuth: Spotify

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.

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

OAuth: A Practical Example

As you saw above, the first thing you need to do is create an application. There’s a great step-by-step explanation on how to do this in the GitHub documentation that you can follow. The only thing to keep in mind is to use the https://httpbin.org/anything URL mentioned above for the Authorization callback URL field.

Once you’ve created your app, copy and paste the Client_ID et Client_Secret, together with your selected redirect URL, into a Python file called github.py:

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 = ""

Now that you have all the important variables in place, you need to be able to create a link to redirect the user to their GitHub account, as explained in the GitHub documentation:

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

In this piece of code, you first define the required parameters that the API expects and then call the API using the requests package and .get().

When you make the request to the /login/oauth/authorize endpoint, the API will automatically redirect you to the GitHub website. In that case, you want to fetch the url parameter from the response. This parameter contains the exact URL that GitHub is redirecting you to.

The next step in the authorization flow is to exchange the code you get for an access token. Again, following the steps in GitHub’s documentation, you can make a method for it:

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"]

Here, you make a PUBLIER request to exchange the code for an access token. In this request, you have to send your CLIENT_SECRET et code so that GitHub can validate that this specific code was initially generated by your application. Only then will the GitHub API generate a valid access token and return it to you.

Now you can add the following to your file and try running it:

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")

If everything goes according to plan, then you should be rewarded with a valid access token that you can use to make calls to the GitHub API, impersonating the authenticated user.

Now try adding the following code to fetch your user profile using the User API and to print your name, username, and number of private repositories:

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"
    )

Now that you have a valid access token, you need to send it on all your API requests using the Authorization header. The response to your request will be a Python dictionary containing all the user information. From that dictionary, you want to fetch the fields name, login, and total_private_repos. You can also print the response variable to see what other fields are available.

Alright, that should be it! The only thing left to do is to put it all together and try it out:

    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)

Here’s what happens when you run the code above:

  1. A link is generated asking you to go to a GitHub page for authentication.
  2. After following that link and logging in with your GitHub credentials, you’re redirected to your defined callback URL with a code field in the query parameters:

    Consuming APIs with Python: Github OAuth Code
    Example GitHub OAuth Code

  3. After pasting that code in your console, you exchange the code for a reusable access token.

  4. Your user information is fetched using that access token. Your name, username, and private repositories count are printed.

If you follow the steps above, then you should get a similar end result to this one:

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

There are quite a few steps to take here, but it’s important that you take the time to really understand each one. Most APIs using OAuth will share a lot of the same behavior, so knowing this process well will unlock a lot of potential when you’re reading data from APIs.

Feel free to improve this example and add more functionality, such as getting your public and starred repositories or iterating through your followers to identify the most popular ones.

There are plenty of great resources online about OAuth, and if consuming APIs behind OAuth is what you really need, then I’d advise you to do a bit more research on that topic specifically. Here are a few good places to start:

From an API consumption perspective, knowing OAuth will definitely come very in handy when you’re interacting with public APIs. Most APIs have adopted OAuth as their authentication standard, and with good reason.

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.

Consuming APIs With Python: Practical Examples

Now that you know all the theory and have experimented with a few APIs, you can consolidate those learnings with some more practical examples. You can modify the examples below to tailor them to your own purposes.

You can follow along with the examples by downloading the source code available at the link below:

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.

Conclusion

There are a million other things you can learn about APIs: different headers, different content types, different authentication techniques, and so on. However, the concepts and techniques you learned in this tutorial will allow you to practice with any API of your liking and to use Python for any API consumption needs you may have.

In this tutorial, you learned:

  • What an API is and what can you use it for
  • Quoi status codes, HTTP headers, and HTTP methods sommes
  • How can you use Python to consume public data using APIs
  • How to use authentication when consuming APIs with Python

Go ahead and try this new magic skill with some public APIs of your liking! You can also review the examples you saw in this tutorial by downloading the source code from the link below:

Further Reading

The APIs used as examples in this tutorial are just a tiny fraction of the numerous public APIs available for free. Here’s a list of API collections that you can use to find your next favorite API:

You can check these out and find an API that speaks to you and your hobbies and maybe inspires you to do a small project with it. If you come across a good public API that you think I or other people reading the tutorial should know about, then please leave a comment below!