Webové API #

Jak už bylo řečeno v lekci o JSON, hlavní výhoda formátu JSON je, že se na Internetu rozšířil nejvíc. Pojďme toho využít!

Spousta webových služeb poskytuje takzvané API (z application programming interface, programátorské rozhraní), přes které je možné s danou službou komunikovat programově. Místo klikání na tlačítka a čtení stránek „očima” dostaneš data ve formátu, kterému rozumí počítače. V dnešní době to bude většinou formát JSON.

Z minulých lekcí bys měl/a mít založený účet na github.com. Podívejme se na to, jak se zeptat Githubu, co o tobě ví.

Autorizace #

První, a mnohdy nejsložitější, krok k použití API je přihlášení. Počítače se totiž přihlašují jinak než lidi a problematika bezpečnosti a oprávnění by vydala na samostatný kurz. My to uděláme co nejjednodušeji, ať se rychle dostaneme k jádru věci:

• Přihlaš se na github.com.
• Jdi na nastavení Personal Accesss Tokens.
• Vytvoř si nový token ("Generate new token"). Nezaškrtávej žádná oprávnění navíc.
• Zkopíruj si token (dlouhý řetězec), které takto dostaneš, do souboru token.txt.

Obsah tokenu se ti zobrazí pouze jednou, hned po vytvoření. Když ho zapomeneš, deaktivuj ho a vytvoř si nový.

Requests #

K práci s internetovými stránkami použijeme knihovnu Requests. V aktivovaném virtuálním prostředí si ji nainstaluj příkazem:

(venv)$ python -m pip install requests

A potom v Pythonu zkus stáhnout nějakou stránku:

import requests

# stažení stránky
page = requests.get('https://github.com')

# ověření, že dotaz proběhl v pořádku
page.raise_for_status()

# vypsání obsahu
print(page.text)

Měl by se vypsat obsah stránky https://github.com – HTML kód, který se objeví když v prohlížeči dáš „Ukázat zdroj” (View Page Source, většinou Ctrl+U) a ze kterého prohlížeč umí vykreslit stránku.

Ale my nechceme obsah pro lidi. Podívejme se, co Github zpřístupňuje počítačům.

Uživatelský účet #

Zkus, co dělá tento kód:

import requests

with open('token.txt') as file_:
    token = file_.read().strip()

headers = {'Authorization': 'token ' + token}

page = requests.get('https://api.github.com/user', headers=headers)
page.raise_for_status()
print(page.text)

Co se stalo? Tím, že jsi Githubu dal/a svůj token (načtený ze souboru, předaný přes „přihlašovací“ slovník headers), poznal, že jde dotaz od tebe a vrátil nějaké informace ve formátu JSON.

Zkus řetězec page.text převést z JSON na slovník a vypsat trochu srozumitelněji:

data = json.loads(page.text)

print(json.dumps(data, ensure_ascii=True, indent=2))

Teď už je lépe vidět celý tvůj profil (možná včetně neveřejných informací – proto musíš svůj token udržovat v tajnosti).

S profilem, který máš v proměnné data, se dá pracovat jako s každým jiným slovníkem. Třeba adresu svého profilového obrázku můžeš vypsat pomocí:

print(data['avatar_url'])

API Githubu #

API Githubu toho umí mnohem víc. Třeba na adrese https://api.github.com/emojis na tebe čeká slovník s adresami malých obrázků. Celé API je zdokumentováno na adrese developer.github.com.

Interakce #

Pomocí webových API se dají informace nejen číst, ale i měnit.

Na stránce github.com/pyvec/naucse.python.cz/stargazers je seznam lidí, kteří „ohvězdičkovali” tyto učební materiály. Je jich zatím málo; pojďme se k nim pomocí webového API přidat.

Napřed svému tokenu (na Githubu v nastavení Personal Accesss Tokens) přidej právo public_repo. Od teď token střež obzvlášť pečlivě, protože se pomocí něj dají informace na Githubu i měnit.

Chceme-li měnit informace, musíme knihovně Requests říct, aby použila jinou „HTTP metodu” než GET. Co to přesně jsou HTTP metody je na trochu delší povídání (viz Wikipedia), ale stručně řečeno, pomocí GET se většinou stahuje obsah, pomocí POST se přidává nový, PUT mění něco, co už na webu existuje a DELETE něco maže. Jakou metodu poujeme závisí na tom, co chceme udělat; většinou to bude POST, PUT nebo DELETE.

Podle dokumentace Githubu se přidání hvězdičky dělá pomocí PUT dotazu na adresu /user/starred/:owner/:repo. Za :owner a :repo dosadíš vlastníka a jméno repozitáře (v našem případě pyvec a naucse.python.cz) a PUT metodu zvolíš tak, že zavoláš místo get funkci put:

import requests

with open('token.txt') as file_:
    token = file_.read().strip()

headers = {'Authorization': 'token ' + token}

page = requests.put('https://api.github.com/user/starred/milandufek/naucse-python', headers=headers)
page.raise_for_status()

Tenhle dotaz nevrátí žádný text, ale na github.com/pyvec/naucse.python.cz/stargazers se můžeš přesvědčit, že to funguje.

Chceš-li hvězdičku zase odstranit, použij metodu DELETE na stejnou adresu. (Ale nezapomeň tam pak ★ zase vrátit! ☺)