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” dostaneme data ve formátu, kterým rozumí počítače – a v dnešní době to bude většinou formát JSON.

Z minulých lekcí bys měla mít založený účet na github.com, tak se zkusme zeptat Githubu, co o nás 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 heslo, které takto dostaneš, do souboru token.txt.

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:

(env)$ 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 dala svůj token (načtený ze souboru, předaný přes 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 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ů. (Tenhle slovník funguje jako vyhledávací tabulka.) 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í ateriá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/pyvec/naucse.python.cz', 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! ☺)