Když API přestane odpovídat, aneb jak se ptát Postmana správně > 자유게시판

• 목록
• 답변
• 글쓰기
• 게시판 리스트 옵션
  • 수정
  • 삭제

Praktická rada: barvy stěn do obýváku dokumentace uveďte i informaci o autentizaci a oprávněních. Frontend potřebuje vědět, které endpointy vyžadují token, jak ho předat a co se stane, když chybí. For those who have any kind of concerns regarding wherever along with tips on how to use více na webu, you can email us from our own page. Uveďte také limity na počet požadavků, pokud existují, a jak je poznáte. To jsou detaily, které se na první pohled nezdají důležité, ale bez nich se frontend zasekne. Až budete psát dokumentaci, zkuste si představit, že ji čte člověk, který nezná vnitřní strukturu backendu. Ptá se: „Co přesně pošlu a co dostanu?" – a vy mu na to musíte odpovědět bez nutnosti ptát se vás.

Než začnete psát test, rozmyslete si, co přesně chcete ověřit. Test by měl mít tři části: připravit vstup, spustit testovanou funkci a porovnat výsledek s očekáváním. Pro začátek si vystačíte s jedním testem pro hlavní scénář. Přidejte až druhý test pro okrajový případ, jako je prázdný řetězec, nulová hodnota nebo extrémně velké číslo. Nepište deset testů najednou – každý test musí mít jasný účel a název, který popisuje chování, ne implementaci. Například místo „test1" použijte „prázdný seznam vrátí nulu".

Při psaní nových testů se vždy ptejte, co se stane, když test selže. Pokud selhání nedává jasnou odpověď na to, která část kódu je rozbitá, test je špatně navržený. Typickou chybou je použití příliš mnoha mocků v integračních testech — tím se z nich stávají jen sofistikované jednotkové testy, které neověřují skutečnou integraci. Místo toho se snažte použít skutečné instance pro ty části systému, které jsou stabilní, a mocky jen pro vnější závislosti, které nelze spolehlivě replikovat (například platební brány).

První testy nemusí být dokonalé – mají vám pomoci pochopit, jak se váš kód chová. Postupně přidávejte testy pro složitější případy a pro části, které se často mění. Vyhnete se tím situaci, kdy oprava jedné chyby rozbije něco, co fungovalo. Unit testy nejsou ztráta času, ale investice do klidu při budoucích změnách. Začněte malým krokem a testy se stanou přirozenou součástí vašeho psaní kódu. Jakmile si osvojíte základy, uvidíte, že testy vám dávají jistotu a šetří čas na ladění.

Jak zajistit, aby dokumentace nezastarala Dokumentace má být živý dokument, ne jednorázový výstup. Nejlepší je generovat ji automaticky z kódu, ale i ručně psaná má smysl, pokud se aktualizuje při každé změně. Stanovte si pravidlo, že žádný endpoint nesmí být nasazen do produkce bez aktualizace dokumentace. Tím se vyhnete situaci, kdy frontend pracuje podle staré verze a backend už dávno odpovídá jinak. Pokud používáte verzování API, dokumentujte každou verzi zvlášť a jasně označte, co je v které verzi nové.

První požadavek vytvoříte snadno: zvolte metodu (GET, POST, PUT, DELETE), zadejte URL a odešlete. Tady ale většina začátečníků dělá zbytečnou chybu – zapomenou na záložku Authorization. Pokud API vyžaduje token, bez něj dostanete 401. V Postmanu nastavte typ autorizace (např. Bearer Token nebo Basic Auth) a token vložte do příslušného pole. Pozor na to, že tokeny často expirují. Proto si do proměnných uložte aktuální hodnotu a při testech ji aktualizujte.

Na závěr si udělejte kontrolní seznam. Zkontrolujte, jestli každý endpoint má uvedenou metodu, cestu, parametry, tělo, odpověď a chyby. Jestli příklady obsahují reálná data a odpovídají schématu. A jestli je dokumentace konzistentní – stejné názvy polí, stejné formáty dat, stejné chybové kódy. Teprve pak můžete říct, že je připravená pro spolupráci. Frontend ocení, když nemusí zkoumat kód, ale může se spolehnout na dokumentaci. Ušetří to čas oběma stranám a hlavně to sníží počet chyb v integraci.

Další podstatné rozhodnutí se týká toho, zda chcete kontrolovat, jak jsou vaše jméno a jméno vašeho projektu používány. Většina licencí obsahuje klauzuli o zřeknutí se odpovědnosti, ale ne všechny zakazují reklamní použití jména autora. Pokud vám vadí, že by někdo použil váš projekt jako součást své marketingové kampaně, vyberte licenci, která to výslovně omezuje. Třeba BSD licence má variantu, která zároveň zakazuje použít jména přispěvatelů k propagaci odvozených děl. To je praktické, ale zároveň to zvyšuje počet povinností, které musíte při distribuci splnit.

Nezapomeňte na chybové stavy. Mnozí backend vývojáři popíší jen happy path a na chyby zapomenou. Přitom frontend musí vědět, jak vypadá odpověď při chybě, jaké stavové kódy se používají a co znamenají. Ideální je pro každý endpoint uvést seznam možných chyb s příkladem odpovědi. Tím se předejde situaci, kdy frontend čeká chybu v jednom formátu, ale API vrací jinou strukturu. Dobré je také specifikovat, jestli API vrací chyby jako řetězec, objekt s kódem, nebo pole chyb.