Python : APIs

Sources

• Le tutoriel que je reprend ici
• Le module requests
• L'API Open-Notify
• L'API Datamuse
• Twilio, un service d'envoi de sms

API : Application Programming Interface

Ou, en francais, interface programmatique. Pour le définir simplement, il s'agit d'un intermédiaire. L'API permet de faire le lien avec un système par son interface, afin d'obtenir facilement ce dont on a besoin. Nous faisons une requête, l'API interroge une application et nous apporte une réponse.

Les APIs sont utiles car elles sont facile d'accès, et permettent au système dont elle sont dépendantes d'évoluer sans que l'on ait à faire évoluer notre code.

C'est parti

Module requests

Le module Python nommé requests sert, comme son slogan l'indique ("HTTP for humans") d'effectuer simplement des requêtes HTTP.Ce module est vraiment simple d'accès, comme le montre le code suivant extrait du site :

>>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
u'{"type":"User"...'
>>> r.json()
{u'private_gists': 419, u'total_private_repos': 77, ...}

Nous allons ici utiliser ce module.

Une API simple

Nous allons ici utiliser l'API de Open Notify, qui est une API servant les données de la NASA. Cool !

Le code

#! /usr/bin/env python3
# encoding: utf-8

###Code d'exemple, servant à apprendre les APIs.

import requests


#Nous commencons par un simple GET
request = requests.get('http://api.open-notify.org')
print(request.text)

'''
Ce code nous renvoie juste le contenu de la page : en effet, nous n'aurons des objetgs précis que si nous ne demandons précisément celui-ci (le bon "end point"). La plupart du temps, nous aurons du JSON en retour (qui est toujours un bon moyen d'organiser des informations). En plus du contenu, nous avons le code de retour.
'''

print(request.status_code) #200 si tout va bien :)

'''
Nous pouvons facilement avoir une erreur 404.
'''

request2 = requests.get("http://api.open-notify.org/nimportequoi")
print(request2.status_code)


'''     Un exemple pratique
Open-notify nous donne plusieurs endpoints pour accéder aux données de la NASA. /iss-now.json nous permet de savoir où est l'ISS; /iss-pass.json à quel moment l'ISS passerait au-dessus de notre tête. Nous allons ici utiliser /astros.json, qui nous donne le nom des personnes actuellement dans l'espace (les veinards...).
'''

astronautes = requests.get('http://api.open-notify.org/astros.json')
print(astronautes.text)

#On récupère nos astronautes suiviss du message "success". 

'''     Du JSON lisible?
Le module requests possède une méthode pour décoder le JSON. On av pouvoir transformer ça en dictionnaire !
'''

astronautes_json = astronautes.json()
print(astronautes_json)

#On peut imprimer tout ça un peu mieux :
print("\n\nNombre de personnes dans l'espace", astronautes_json['number'])

for a in astronautes_json['people']:
    print(a['name'])

Une autre API, un autre jour...

Nous allons maintenant utiliser Datamuse, qui est une API servant à faire des recherches de mots en anglais. ON peut chercher des mots commencant par telle lettre, qui riment, etc...

Des paramètres

À ce stage nous allons découvrir que l'on peut utiliser des paramètres dans l'url. La requête que nous passons est un paramètre (*query parameters*) utilisé pour appliquer des contraintes.

==Le code==#! /usr/bin/env python3

1. encoding: utf-8

import requests

1. 1. 1. Deuxième partie du tuto APIs

Les paramètres sont des demandes que nous plaçons directement dans l'URL afin d'obtenir ce que l'on veut. Nous avons deux façons de faire. La première consiste à passer directement quelque chose dans l'url.

1. Trouver les rhymes de "jingle"

r = requests.get("https://api.datamuse.com/words?rel_rhy=jingle")

1. print(r.json()) #Encore du JSON !

Ici, le endpoint est "word", et nous plaçons un ? afin d'appliquer des paramètres. rel_rhy est le mot-clef demandant des rimes riches avec le mot en question. Pour la seconde façon de faire, on peut trouver quelque chose de plus "pythonique" en créant une variable acceptant un dico clef : valeur.

param = {"rel_rhy":"jingle"} r = requests.get("https://api.datamuse.com/words", param)

1. Le résultat est le même.

1. 1. 1. Amusons-nous.

1. Les mots en lien avec le mot "grape" qui commencent par la lettre j.

param = {'ml':'grape', 'sp':'j*'} r = requests.get("https://api.datamuse.com/words", param)

1. Il faut formater r avant de l'utiliser ! Le JSON est utilisable assez facilement.

for i in r.json():

   print(i['word'])

</nowiki>

Envoyer des SMS en Python ?

On peut faire des choses sympas, comme récupérer des données et les envoyer par SMS ! Twilio est une plateforme de dev permettant aux applications d'envoyer de la voix, de la vidéo et des messages. Je passe les étapes, que je me contenterais de citer ici directement depuis le tutoriel, pour utiliser twilio :

   Sign up on twilio and create a free trial account.
   When you sign up you will be asked to verify your personal number.
   Once you verify the number you will be asked to create a new project.
   After you create your project you can access your dashboard and here you can find AccountSID that looks something like ACxxxxxxxxxx and an aunthentication token. Make a note of these two.
   You will need to create a twilio free/paid number that can be used to send sms.
   To do this, in the menu chose Phone Numbers,with trial account you get free credits, use it to buy a phone number.
   Once the number is created, you can view it in the Active numbers tab.

Nous allons aussi utiliser le module twilio, qui nous permettra de l'utiliser.

python3 -m pip install twilio

Le code

#! /usr/bin/env python3
# encoding: utf-8

from twilio.rest import Client
import requests

#SID AC4f1d99adeb5e506572184ba19f0e03b1
#Auth 0ed69138f110c6b8eea16b94b409f103
#Number +12029155259

#On définit l'identifiant et le token de connexion.
account_sid = 'AC4fxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'xxxxxxxxxxxxxxxxxxxxx'

#On crée l'objet client.
client = Client(account_sid, auth_token)

#On récupère les données spatiales...
r = requests.get('http://api.open-notify.org/astros.json')
people = r.json()

number_iss = people['number']

#Contenu
Message = "Salut, il y'a actuellement {} personnes dans l'espace.".format(str(number_iss))


#On formule le message à envoyer et on l'envoie !
message = client.messages.create(\
        to="+336xxxxxxxxx",\ #Doit être un numéro vérifié, voir la console Twilio pour avoir le bon format
        from_="+120xxxxxxxx",\ #Numéro depuis lequel j'envoie
        body=Message) #Corps du message

print(message.sid)