Fabiobot: Vyzkoušíme Strava API a převedeme zdolané kilometry na kole na seřazené škodovky

Letní prázdniny se nám přehouply do druhé poloviny a červencové tropy vystřídala zakaboněná obloha a déšť. Mnozí tedy nahradili opalovací krém za pohorky nebo třeba cyklistickou helmu.

Prozkoumejte další články ze seriálu Pojďme programovat elektroniku

Dnes se proto v našem seriálu o programování elektroniky seznámíme s aplikačním rozhraním pro vývojáře, které nabízí populární služba Strava.

Strava je nejpopulárnější aplikace pro záznam outdoorové aktivity počínaje nedělním výletem s rodinou na Kokořín a konče cestou na kole do práce 

API pro sportovce

Pokud vám tento web nic neříká, pravděpodobně nemáte v garáži kolo, nebo alespoň v botníku běžecké boty, Strava totiž patří k největším službám pro rekreační i profesionální sportovce, kteří zde ukládají své aktivity a poměřují se s ostatními.

Každý uživatel Stravy si může vytvořit aplikaci a přistupovat k datům pomocí API 

Pro nás je podstatné to, že web nabízí i docela povedené aplikační rozhraní, které není určené jen pro velké ryby na trhu, ale i pro domácí kutily. Ti si mohou po registraci účtu vytvořit zdarma jednu soukromou aplikaci, která dokáže strojově pracovat prakticky se všemi daty sportovců, kteří vpustí apku k sobě na profil.

Fabiobot převede kilometry na škodovky

Podobná základní aplikace může provést 200 dotazů do databáze služby každých 15 minut, nejvýše ale 2 000 dotazů denně. Hodí se tedy opravdu pro malé osobní projekty. Takový prográmek by mohl třeba vám a vašim blízkým počítat nejrůznější statistiky, které jinak nejsou součástí samotné Stravy.

Toto bude výsledek dnešních hrátek. Fabiobot se spojí skrze API s účtem uživatele, zjistí, kolik zaznamenal kilometrů na kole a tuto hodnotu vyjádří počtem seřazených fabií 

Dnes si to vyzkoušíme, abychom ale začátečníky hned na začátku nevyděsili hromadou složitého kódu, vyrobíme si naprosto primitivní aplikaci Fabiobot. Znalci internetových vtípků a memů už jistě tuší, co bude jejím úkolem. Náš Fabiobot spočítá vaše na kole ujeté kilometry a převede je na počet fábií postavených jedna za druhou.

Děláme si tak legraci z legendárních mediálních zkratek, kdy občas tiskem prolétl přepočet, kolik fábií za sebou měřil na délku R.M.S. Titanic, kolik fotbalových hřišť zabere Mezinárodní vesmírná stanice a tak podobně.

Autentizační ping-pong standardu OAuth

Fabiobot se bude skládat z webového serveru napsaného v Pythonu a z HTML/JS stránky se samotnou uživatelskou statistikou. Server spustíme na lokálním počítači, takže bude dostupný na místní IP adrese 127.0.0.1. V produkční verzi bychom jej mohli umístit někam na veřejný internet, na NAS, pokud to umožňuje, Raspberry Pi atp.

Vstupní bod naší aplikace s žádostí o autorizaci

Největší překážkou pro začátečníky bude komplexní autentizace typu OAuth – Open Authorization. V praxi to znamená, že k API nepřistupujeme podobně jako minule pomocí nějakého vlastního a pevně daného klíče, ale musíme vygenerovat dočasný klíč pro každého uživatele Stravy, který bude chtít používat Fabiobot.

Generování dočasného klíče – tokenu – nebudeme dělat přímo my, ale provede to sám uživatel po vstupu na web Fabiobotu. Najde na něm totiž velké tlačítko „Autorizuj mě,“ které po klepnutí návštěvníka přesměruje na adresu:

Po načtení adresy se zobrazí autorizační dialog Stravy, který návštěvníka požádá, aby se přihlásil svým účtem a potvrdil práva, o která žádá aplikace Fabiobot. Tu v adrese reprezentuje její jedinečný identifikátor 108836 a práva pak parametr scope a jeho hodnota activity:read_all.

Žádáme tedy o přístup k základním informacím o sportovci, ale zároveň o přístup ke všem jeho aktivitám. V našem dnešním příkladu to sice až tak nevyužijeme, stejná práva ale budete potřebovat, pokud byste si chtěli naprogramovat třeba aplikaci, která bude přistupovat ke všem sportovním záznamům v celé vaši historii. Třeba kdybyste si chtěli naprogramovat vlastní mapu projetých tras a tak podobně.

Autorizační dialog na serveru Stravy

Jakmile návštěvník potvrdí dialog, Strava jej v prohlížeči přesměruje na adresu, která je součástí původní URL a my ji také ztučnili: 127.0.0.1/fabiobot/exchange_token.

Ještě jednou, příklad testujeme na lokálně spuštěném serveru, takže nás Strava přesměruje právě na ten. V produkční verzi bychom nahradili záznam třeba doménou fabiobot.cz, veřejnou IP adresou apod.

Ping-pong pokračuje žádostí o přístupový token

Celá adresa, na kterou Strava přesměruje komunikaci a doplní pár svých parametrů, bude nakonec vypadat zhruba takto:

Strava v parametru scope potvrzuje udělená práva, naprosto klíčovou hodnotou pro dokončení autentizačního OAuth ping-pongu je ale hodnota parametru code. Obsahuje dočasný token, který použijeme k finální žádosti o vygenerování přístupového tokenu pro právě řešeného uživatele.

HTTP žádost o vygenerování přístupového tokenu bude vypadat takto:

Všimněte si, že je součástí adresy opět numerický identifikátor naší aplikace client_id, zároveň dočasný code, který jsme získali v předchozím kroku, a ještě alfanumerický řetězec secret, který společně s numerickým identifikátorem aplikace najdeme v její konfiguraci na webu Stravy (viz odkaz v úvodu).

Jakmile dotaz odešleme, webový server Stravy konečně odpoví strukturou JSON, ve které jsou uložené přístupové údaje pro uživatele. Když jsem se tedy tímto způsobem přihlásil k Fabiobotu pod svým uživatelským jménem Jakuba Čížka, dorazila tato odpověď:

{
  "token_type": "Bearer",
  "expires_at": 1687993572,
  "expires_in": 21600,
  "refresh_token": "5eed5fd25sd5ffgds5g5dg5gsr2",
  "access_token": "55f858rsg55gs5r2r2vr5g2g2grd",
  "athlete": {
    "id": 21641236,
    "username": "ek_jakub",
    "firstname": "Jakub",
    "lastname": "Čížek",
    "city": "Brno",
    "state": "Jihomoravský kraj",
    "country": "Česko",
    "sex": "M",
    "premium": true,
    "created_at": "2017-05-02T12:17:05Z",
    "updated_at": "2022-10-16T22:00:13Z",
  }
}

JSON jsem o něco málo zkrátil, aby se nám vůbec vešel do článku. Na první pohled je jasné, že obsahuje popisné informace o sportovci na Stravě, pro nás jsou v tuto chvíli ale zdaleka nejdůležitější hodnoty access_token a expires_at. Access_token je klíč, který může Fabiobot používat při dotazování se na Strava API, přičemž služba bude vědět, k čemu všemu má token práva a k jakému uživateli a aplikaci se váže.

Jak už ale napovídá druhá zmíněná hodnota expires_at, přístupový klíč má omezenou časovou platnost, takže za pár hodin už nebude fungovat a musíme celé autentizační kolečko zopakovat.

Pokud v tom už máte pěkný guláš, snad vám napoví toto schéma celého autorizačního kolečka pomocí techniky OAuth