Jak sestavit dokumentaci API, kterou frontend využije

COPY . .

Když stojíte před návrhem API, první otázka obvykle zní: REST, nebo GraphQL? Odpověď není černobílá. REST je starší a osvědčený přístup, GraphQL přináší flexibilitu, ale také složitost. Základní pravidlo: pokud potřebujete rychlé nasazení, For more information regarding Rady Pro Rekonstrukci look at our own web site. stabilní dokumentaci a jednoduchou cache, zvolte REST. Pokud řešíte aplikace s mnoha různými klienty (mobil, web, desktop) a datové nároky se liší, GraphQL může ušetřit čas i přenos dat.

Nakonec si osvojte dvě užitečné dovednosti: vracení změn a prohlížení historie. Když zjistíte, že jste rozbili aplikaci, nepropadejte panice. Stačí se podívat na poslední commity a vrátit se o krok zpět. Užitečné je také porovnat aktuální stav se starší verzí souboru – to vám pomůže najít, co přesně se změnilo. Pravidelný trénink s těmito nástroji vám dá jistotu a webové projekty přestanou být noční můrou. Začněte ještě dnes a za týden nebudete chtít pracovat jinak.

Když backend dodá rozhraní bez pořádné dokumentace, frontend často tápá, doptává se na Slacku a píše si vlastní poznámky. Výsledkem jsou zbytečné chyby, zpoždění a frustrace. Přitom stačí dodržet pár zásad, které z dokumentace udělají nástroj, ne nutné zlo. Tento článek se zaměřuje na praktické kroky, jak dokumentaci připravit tak, aby sloužila oběma stranám – a hlavně aby se v ní dalo rychle a spolehlivě hledat.

Nejprve si inicializujte repozitář přímo v kořenovém adresáři projektu. Tím vytvoříte skrytou složku, která uchovává historii. Do ní se ukládají pouze soubory, které explicitně přidáte, takže se nemusíte bát, že se do verzování dostanou dočasné soubory nebo hesla. Než začnete commitovat, vytvořte si soubor .gitignore a zadejte do něj složky jako node_modules, .env, vendor nebo cache. Bez tohoto kroku riskujete, že do historie uložíte stovky zbytečných souborů a případně i citlivé údaje.

Pro testování požadavků, které mění data (POST, PUT), využijete sekci Body. Zvolte formát raw a typ JSON, případně form-data, pokud posíláte soubory. Tělo požadavku musí být validní JSON – to znamená správně uzavřené závorky a uvozovky. Typická chyba je chybějící čárka mezi objekty, což způsobí chybu 400. Postman má vestavěný validátor, který zvýrazní syntaxi, ale ne osvětlení v obývákuždy chybu odhalí. Pokud server vrací chybu, zkuste nejprve zkontrolovat tělo požadavku, jestli odpovídá schématu z dokumentace. Pomáhá také použít funkci Pretty, která zformátuje JSON a usnadní čtení.

EXPOSE 3000

U RESTu se držte konvencí: zdroje, HTTP metody, stavové kódy. Typická chyba? Používat GET pro operace, které mění data, nebo ignorovat HTTP kódy jako 404 či 409. Místo toho definujte jasné endpointy, např. /users a /users/123. Pro cache použijte hlavičky Cache-Control a ETag. To je praktické, pokud máte veřejné API nebo mnoho opakovaných dotazů. Pozor na over-fetching – REST vrací vždy celé objekty, takže pokud potřebujete jen jméno uživatele, stáhnete i jeho e-mail či adresu.

Při přechodu z RESTu na GraphQL nebuďte unáhlení. Nejlepší je začít hybridně – nechat stávající REST endpointy a GraphQL představovat jako novou vrstvu pro vybrané případy. Tím minimalizujete riziko a získáte zpětnou vazbu. Při návrhu GraphQL schématu používejte sémantické názvy typů a polí. Vyhněte se polím s názvy jako data2 nebo info. A nezapomeňte na verzování – i GraphQL potřebuje strategii, jak řešit změny v schématu, i když to není tak formální jako u RESTu.

Praktický příklad je k nezaplacení. Místo suchého výpisu parametrů ukažte kompletní JSON s reálnými hodnotami. Uveďte i příklady s hraničními hodnotami – prázdný seznam, null, dlouhý text. Frontend pak vidí, co může očekávat, a nemusí hádat. Pozor ale na citlivé údaje: v příkladech nikdy nepoužívejte skutečná osobní data nebo tokeny. Stačí fiktivní e-maily typu "jmenoprijmeni" – nikdy ne skutečná adresa.

Jak psát efektivní testy a vyhnout se chybám Při psaní testů se vyvarujte dvou častých chyb. První je spoléhat se na vizuální kontrolu odpovědi – to je zdlouhavé a snadno se přehlédne chyba. Druhá je testovat jen jeden stav – vždy testujte úspěšný i neúspěšný scénář. Například u přihlášení zkuste špatné heslo a ověřte, že API vrátí status 401. Postman umožňuje ukládat proměnné, které se dají použít v testech – třeba token z přihlášení, který pak použijete v dalších požadavcích. Proměnnou nastavíte v sekci Tests pomocí pm.globals.set('token', responseBody). Pak ji použijete v URL nebo hlavičce jako dvojité složené závorky, například token.

Nezapomeňte na testy – Postman umožňuje psát automatické testy v JavaScriptu. Po odeslání požadavku můžete ověřit, že status kód je 200, že odpověď obsahuje určitou hodnotu, nebo že je JSON struktura správná. Například test, který kontroluje, že odpověď obsahuje pole 'id', vypadá takto: pm.test('Kontrola ID', function() pm.response.to.have.jsonBody('id'); );. Tyto testy se ukládají do požadavku a spouští se při každém odeslání. To je užitečné pro regresní testování – když změníte API, hned víte, co se rozbilo. Začněte s jednoduchými testy a postupně přidávejte složitější.