Akademie 02 - REST API

REST API

REST API je oblíbený, jednoduchý a snadno čitelný druh API. Rozhraní zajišťuje funkci pro předávání dat s ostatními aplikacemi. REST je obecný mechanizmus, který dává sadu doporučení a omezení.

Různé druhy API mají prakticky všechny aplikace zejména webové. Dokonce některé nové webové technologie jsou na komunikaci stránky, kterou vidíme v prohlížeči, a dotazování na server s ohledem na naši aktivitu v aplikaci přímo založeny. Jak API funguje se lze i vizuálně podívat na tematická videa třeba na YouTube.

Co to api je:

a jak API funguje:

Přístup k API přes URL

K REST API přistupujeme prostřednictvím protokolu HTTP/S a URL adres, které známe z přístupu k webovým stránkách prostřednictvím prohlížeče.

URL adresa může vypadat například https://api.freelo.cz/v1/projects/

Finální implementace a složení URL se drobně liší aplikace od aplikace. URL obsahuje v uvedeném příkladu adresu rozhraní https://api.freelo.cz/, verzi API v1/ a v neposlední řadě endpoint projects/, tedy místo, které žádáme o data.

URL adresa může obsahovat mnoho dalších informací. Pro ukázku další příklad https://api.freelo.cz/v1/work-reports?date_reported_range%5Bdate_from%5D=2021-02-01&date_reported_range%5Bdate_to%5D=2021-02-28 kdy za endpointem work-reports následuje znak ? který značí, že budou následovat další parametry, které se poté dají řetězit znakem &.

Znaky jako [] a další se kódují, aby vyhovovala standardům URL např. na [ = %5B a ] = %5D. Každá knihovna pracující s URL má ke kódování/dekódování nástroj. Případně lze využít online nástroje. Vyhledejte hesla URL encoder/decoder.

HTTP metody

Zvolenou metodou, kterou URL prostřednictvím HTTP voláme deklarujeme, co od API chceme. Standardně jsou k dispozici základní čtyři metody, ale existuje jich více:

• GET - získání dat
• POST - vložení dat
• PUT - úprava dat
• DELETE - smazání dat

JSON struktura

JSON se stal standardním formátem pro předávání dat v rámci API. Tímto formátem posíláme data, která chceme API předat a stejně tak takto data získáváme. Ukázka získaných dat z API.

{
    "total": 4013,
    "count": 100,
    "page": 0,
    "per_page": 100,
    "data": {
        "reports": [
            {
                "id": 2298977,
                "date_add": "2022-04-07T08:36:27+02:00",
                "date_reported": "2022-04-07T06:41:19+02:00",
                "note": "fakturace",
                "minutes": 116,
                "cost": {
                    "amount": "0",
                    "currency": "CZK"
                },
                "task": {
                    "id": 4792264,
                    "name": "Fakturace"
                },
                "tasklist": {
                    "id": 509200,
                    "name": "Pravidelné úkoly"
                },
                "project": {
                    "id": 187549,
                    "name": "C- managment",
                    "labels": [
                        "connexa it"
                    ]
                },
                "author": {
                    "id": 4914,
                    "fullname": "Tomáš Haubert"
                },

Stavové kódy

Po odeslání dotazu nám API kromě odpovědi vrací i stavový kód, jak se s naším požadavkem popasoval. Nejraději vidíme stav 200 OK, to znamená, že požadavek proběhl v pořádku. Stavů je celá řada. Podrobný výpis naleznete třeba v článku na IT Network.

Dokumentace

Kvalitně zdokumentované API je základem úspěchu jeho vhodné implementace. Existuje mnoho nástrojů, jak jej vhodně popsat. Jedním z nejlepších a nejrozšířenějších je původně český startup Apiary.io. Jak vypadá konkrétní dokumentace se můžete podívat třeba na aplikace Freelo.

Nástroje pro testování

Ve chvíli, kdy chceme začít s API pracovat, nejdříve potřebuje nějaký šikovný program pro jeho testování. Mně se odsvědčil Postman a na iPadu používám Rest – HTTP API Client.

Autorizace

Víme, k čemu API slouží, v dokumentaci jsme si našli endpointy, se kterými chceme pracovat, a máme nástroj pro práci. Pro otestování nástroje a práci lze pracovat s veřejnými API pro tyto účely. Někdy jsou i vtipné nebo se zajímavou tématikou třeba ze světa Star Wars. V praxi se budeme setkávat se zabezpečenými rozhraními. Možností, jak se autorizovat, je celá řada. Často se setkáme s variantou Basic, kdy se z našeho uživatelského jména a hesla vytvoří hash, který se pošle v hlavičce dotazu. Obvyklá je také varianta uživatelské jméno (email) a API klíč, který si vygenerujeme v uživatelském profilu aplikace ke které přistupujeme.

Ukázka

Ve videu si shrneme informace z článku a otestujeme API s reálnými daty.