3. REST rozhraní

1. seznámení s REST API Stopařův průvodce REST
2. Vytvoření vlastních URI pro hlavní metody REST API
3. Vytvoření backend aplikace s REST API

API, neboli rozhraní pro programování aplikací (anglicky Application Programming Interface), je sada definovaných pravidel, protokolů a nástrojů, které umožňují různým softwarovým aplikacím komunikovat a integrovat mezi sebou. Jedná se o most, který umožňuje propojení mezi různými částmi softwaru, aby mohly vzájemně spolupracovat a využívat své funkcionality.

Existuje několik důvodů proč vytvářet API:

• Zjednodušení integrace - API umožňuje různým aplikacím snadno integrovat a sdílet data a funkcionality, což vede k větší efektivitě a flexibilitě v softwarovém vývoji
• Rozšíření dostupnosti - Otevření funkcionalit aplikace prostřednictvím API umožňuje třetím stranám jako jsou externí vývojáři, partneři a další, vytvářet nové aplikace nebo rozšířit stávající funkcionality.
• Centralizace dat - API může sloužit jako centrální bod přístupu k datům a funkcionálním službám, což usnadňuje interoperabilitu mezi různými systémy a aplikacemi.

REST API (Representational State Transfer Application Programming interface) je jedním z nejpoužívanějším typů API. Je navržený tak, aby byl jednoduchý, flexibilní a snadno školovatelný pro komunikaci mezi klienty a serverem pomocí standardních HTTP metod a formátů dat, jako je JSON.

REST API organizuje datové entity (zdroje) do jedinečných URL adres. Technicky nejde o URL, ale o URI (Uniform Resource Identifiers), které rozlišují různé typy datových zdrojů na serveru. Klient může získat data o zdroji tím, že požádá o přístup k tomuto koncovému bodu pomocí protokolu HTTP.

Zpráva požadavku má velmi specifický formát. Nejdůležitější je Start řádek, který obsahuje URI, ke kterému chce klient přistoupit a HTTP metodu požadavku, která signalizuje záměry klienta s daným zdrojem.

Pod Start řádkem se nachází hlavičky, které obsahují metadata o požadavků. Hlavička accept může serveru říct, že má připravit data ve specifickém formátu, nebo hlavička authorisation může být použita k tomu, aby serveru sdělila, že má klient dostatečná oprávnění pro daný HTTP požadavek. Po hlavičkách následuje tělo, které obsahuje vlastní soubor dat.

Po přijetí zprávy požadavku provede server určitý kód (obvykle čtení z databáze), který může být následně zformátován do zprávy s odpovědí. Začátek zprávy obsahuje stavový kód, který klientovy sděluje, co se stalo s jeho požadavkem. Kódy na úrovni 2xx znamenají, že všechno proběhlo v pořádku, na úrovni 4xx znamenají, že s požadavkem bylo něco špatně, a na úrovni 5xx znamenají, že server selhal.

Po stavovém kódu následují hlavičky odpovědi, které obsahují informace o serveru. Po nich následuje tělo odpovědi, které obsahuje soubor dat a obvykle je formátováno v JSON.

Důležitou součástí této architektury je, že je bez-stavová. To znamená, že obě strany nepotřebují uchovávat žádné informace o sobě navzájem. Každý cyklus požadavek - odpověď je nezávislý na ostatní komunikaci. To vede k dobře fungujícímu chování, které je předvídatelné a spolehlivé.

První vrstvou REST API je resource. Ta představuje jednotlivé entity nebo datové objekty, které jsou dostupné prostřednictvím REST API. Každý zdroj je identifikován pomocí jedinečné URL adresy, která slouží jako adresa pro přístup k danému zdroji. URL adresy jsou navrženy tak, aby byly intuitivní a snadno čitelné.

Resource vrstva je základním stavebním prvkem REST architektury, který umožňuje jednoduchou a hierarchickou organizaci dat a funkcionalit v rámci API. Díky jasně definovaným zdrojům a jejich URL adresám je snadné porozumět struktuře API a provádět operace s daty pomocí standardních HTTP metod.

Uvažujme jednoduchý příklad aplikace pro správu knihoven. V této aplikaci může být každá kniha reprezentována jako zdroj. URL adresy pro manipulaci s knihami by mohli vypadat například takto:

• /books: Seznam všech knih
• /books/{id}: Konkrétní kniha identifikovaná pomocí jejího jedinečného identifikátoru.

Druhou vrstvou REST API jsou HTTP metody, které umožňují klientům provádět různé operace s daty uloženými na serveru. Tyto metody definují způsoby, jakými se klienti mohou dotazovat, vytvářet, aktualizovat a mazat data prostřednictvím jednoduchých HTTP požadavků.

Správné použití HTTP metod je důležité pro navrhování srozumitelných a efektivních REST API. Každá metoda má svůj vlastní účel a zajišťuje, že API je konzistentní, jednoduché na použití a bezpečné. Použití standardních HTTP metod také umožňuje snadnou integraci s různými nástroji a frameworky pro vývoj.

Hypermedia Controls, často označované jako HATEOAS (Hypermedia as the Engine of Application State), poskytuje klientům dynamické odkazy na další dostupné akce nebo zdroje v rámci API. Tím umožňuje klientům objevovat a integrovat s funkcionalitou API bez předchozí znalosti nebo pevně daného rozhraní.

Hypermedia Controls přináší do REST API flexibilitu a samo-popisnost, což usnadňuje jeho používání a rozšiřování. Klienti mohou interagovat s API bez pevné znalosti jeho struktury a provádět operace v souladu s aktuálním stavem aplikace.

Uvažujme, že klient pošle požadavek na získání informací o konkrétní knize. Server mu v odpovědi poskytne nejen samotná data o knize, ale také odkazy na další akce, které může klient provést.

{
    "title": "Python Programming",
    "author": "John Smith",
    "links": [
        {"rel": "self", "href": "/books/1"},
        {"rel": "update", "href": "/books/1", "method": "PUT"},
        {"rel": "delete", "href": "/books/1", "method": "DELETE"},
        {"rel": "related", "herf": "/authors/johnsmith"}
    ]
}

Pro efektivní manipulaci s HTTP požadavky a odpověďmi ve frameworku Flask jsou k dispozici dva důležité balíčky: request a jsonify. Tyto balíčky umožňují zpracovávání dat v rámci REST API a usnadňuje komunikaci mezi klienty a serverem.

Balíček request umožňuje zpracování HTTP požadavků, které klienti odesílají serveru, a poskytuje snadný způsob, jak získat přístup k jednotlivým částem těchto požadavků, jako jsou zdroje, hlavičky nebo metody. Základní funkcionalitou balíčku request je získávání dat z požadavků ve formě JSON, formulářů nebo parametrů URL.

@app.route('/tasks', methods=['POST'])
def create_task():
    new_task = request.json
    new_task['id'] = get_task_id()
    tasks.append(new_task)
    return jsonify(new_task), 201

Ve funkci create_task() používáme request.json, abychom získali data, která klient posílá v těle požadavku při vytváření nového úkolu. Tato data jsou použita k vytvoření nového úkolu a uložení do seznamu úkolů.

Balíček request také umožňuje získání informací o metodě požadavku (request.method), o adrese URL (request.url) nebo o hlavičkách (request.headers).

Balíček jsonify umožňuje serializaci dat do formátu JSON a vytvoření odpovědi do formátu JSON.

tasks = [
    {"id": 1, "title": "Task 1", "description": "Task 1 desc"},
    {"id": 2, "title": "Task 2", "description": "Task 2 desc"},
]
 
@app.route('/tasks', methods=['GET'])
def get_tasks():
    return jsonify(tasks)

// Výstup z jsonify(tasks)
[ 
    { 
        "id": 1, 
        "title": "Task 1", 
        "description": "Task 1 desc" 
    }, 
    { 
        "id": 2, 
        "title": "Task 2", 
        "description": "Task 2 desc" 
    } 
]

Implementujte do stávající Flask aplikace REST API

• URI endpointy pro API oddělte od ostatních endpointů do vlastního api_routes.py souboru.
• Endopointy budou mít prefix /api/<api endpoint>.

Funkce API:

• Vložení hodnoty {“timestamp”: value, “temp”: value} pomocí vhodně zvolené metody. Hodnotu timestamp můžete generovat automaticky na serveru.
• Získání poslední hodnoty {“timestamp”: value, “temp”: value}.
• Získání posledních X naměřených hodnot.
• Smazání nejstarších Y naměřených hodnot.
• Další funkce dle vašeho uvážení

Odevzdání:

• Ukázat funkční aplikaci na cvičení,
• Nahrát na fakultní GitLab (commit již existujícího projektu),
• Do brute nahrát url na commit.