První kroky s API: praktický průvodce pro začátečníky

Při práci s více jazyky narazíte také na rozdíly v datech, číslech a měnách. Formát data „03/04/2025" znamená v češtině 3. dubna, v angličtině 4. března. Proto nikdy netvrďte formát ručně, ale používejte funkce pro lokalizaci z vaší knihovny. Stejně tak desetinná čárka, mezery mezi tisíci nebo symbol měny se liší. Všechny tyto hodnoty by měly být součástí lokalizačního systému, ne pevně zapsané v kódu. Uživatele byste tím zmátli a v některých případech by mohli nesprávně interpretovat důležité údaje.

Pro celkové rozvržení stránky sáhněte po Gridu. Definujte si základní mřížku pomocí grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)). Tento trik zajistí, že se sloupce automaticky přizpůsobí šířce obrazovky bez jediného media query. Můžete tak mít tři sloupce na desktopu, dva na tabletu a jeden na mobilu, aniž byste psali jediný řádek kódu navíc. Jen si dejte pozor, aby minimální šířka nebyla příliš velká – pak by na malých displejích zůstávaly jen jeden až dva sloupce, což nemusí být vždy žádoucí.

Pokud jde o strukturu projektu, neházejte všechno do jednoho souboru. Rozdělte kód na moduly – oddělte routes, controllers a služby pro práci s daty. Tím získáte přehlednost a usnadníte si testování. Pro menší API stačí i tři soubory, ale pro větší projekty je dobré zavést složkovou strukturu. Důležité je taky myslet na CORS – pokud vaše API budou volat prohlížeče z jiné domény, musíte povolit příslušné hlavičky, jinak požadavky skončí chybou.

Při samotném psaní zdrojových textů myslete na délku. Česká věta je často delší než anglická, a pokud máte tlačítko s pevnou šířkou, text se ořízne. Vždy testujte, jak se překlad chová v extrémních případech — nejdelší slovo, nejdelší věta, nejdelší číslo s jednotkou. Stejně tak pozor na složené výrazy. V češtině skloňujeme, takže věta „Máte 3 nové zprávy" se nedá jednoduše poskládat z částí „Máte" + číslo + „nové zprávy". Používejte raději celé věty s placeholdery, než abyste spojovali kusy textu podle počtu.

Dalším častým problémem je kódování a speciální znaky. Pokud používáte soubory s překlady, vždy je ukládejte v UTF-8, jinak se diakritika rozsype. Stejně tak si dejte pozor na apostrofy a uvozovky — v některých formátech se musí escapovat, a pokud to uděláte špatně, aplikace spadne. Před nasazením si vždy spusťte automatizovaný test, který ověří, že všechny klíče existují ve všech jazycích a že žádný soubor neobsahuje syntaktickou chybu. Tím odhalíte problém dřív, než se dostane k uživatelům.

Když začnete do jednoho projektu přidávat druhý nebo třetí jazyk, rychle zjistíte, že chaos vzniká spíš z organizace než z překladu samotného. Nejčastější chybou je ukládat texty přímo do zdrojového kódu, ať už jde o web, mobilní aplikaci nebo desktopový nástroj. Jakmile potřebujete změnit jednu větu, musíte hledat v desítkách souborů a riskujete, že něco přehlédnete. Mnohem lepší je oddělit veškeré texty od logiky aplikace a držet je v jednotném formátu, který podporuje klíče a hodnoty.

Nejprve si vyberte jedno jednoduché veřejné API, které vás zajímá – třeba pro počasí, kurzy měn nebo seznam států. K tomu budete potřebovat nástroj pro testování požadavků, jako je nástroj příkazové řádky nebo grafický klient. Klíčové je naučit se číst dokumentaci. Každé API má popis koncových bodů (adres, na které se posílají požadavky), povolené metody (GET, POST, PUT, DELETE) a parametry. Vyzkoušejte si nejprve GET požadavek, který pouze získává data – je nejbezpečnější a nezpůsobí žádné změny.

Na závěr – testujte. Není nutné psát stovky testů, ale pokryjte alespoň hlavní endpointy a ošetření chyb. K tomu se hodí nástroje jako Supertest, které vám umožní simulovat HTTP požadavky bez spuštění serveru. Pozor si dejte na time-outy u asynchronních operací a na správné ukončení serveru po testech, jinak se vám procesy zablokují. S trochou disciplíny a dodržováním těchto zásad bude vaše REST API stabilní a snadno rozšiřitelné.

Třetí úskalí spočívá v tom, že lidé často spouští kontejnery interaktivně bez náležitého přepínače. Pokud potřebujete vejít do běžícího kontejneru a prozkoumat ho, použijte docker exec -it název_kontajneru sh. Bez -it se nedostanete do interaktivního shellu a budete jen bezradně koukat na výstup. Také si zvykněte na pravidelný úklid: příkaz docker system prune smaže nepoužívané obrazy, kontejnery a sítě, čímž uvolní místo na disku. Naopak se vyvarujte mazání kontejnerů, které právě běží – vždy je nejprve zastavte příkazem docker stop.

Návrh routes a práce se status kódy Při návrhu routes se držte REST konvencí. Používejte podstatná jména v množném čísle (například /users), vyhněte se slovesům a akce odvozujte od HTTP metod. GET pro čtení, POST pro vytvoření, PUT nebo PATCH pro úpravu a DELETE pro mazání. Zásadní je vracet správné HTTP status kódy – 200 pro úspěch, 201 pro vytvoření, 400 pro chybný požadavek, 404 pro nenalezený zdroj a 500 pro interní chybu. Častou chybou je vracet 200 i při chybě, což klientovi znemožní rozlišit úspěch od selhání.