Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási:
„API vracia chybu.“
Vývojár sa pýta:
„Aký endpoint? Aké parametre? Aký stavový kód?“
Tester nevie odpovedať.
V dokumentácii je len zoznam endpointov.
Bez parametrov. Bez príkladov. Bez chýb.
Výsledok:
API existuje.
Ale nedá sa použiť bez vývojára.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v API.
Problém je v tom, že dokumentácia nepopisuje správanie.
Častý stav:
- zoznam endpointov
- názvy metód
- nič viac
Chýba odpoveď na základnú otázku:
Čo sa stane, keď to zavolám?
API dokumentácia nie je zoznam URL.
Je to opis komunikácie medzi systémami.
Skutočné náklady (čas, chaos, riziko)
Keď API dokumentácia nie je kompletná:
- integrácie sa robia pokus-omyl
- tester nevie pripraviť testy
- support nevie analyzovať chybu
- vznikajú konflikty medzi tímami
Typická situácia:
endpoint funguje
ale nikto nevie, ako ho správne použiť
Minimálny model riešenia
API dokumentácia nemusí byť zložitá.
Ale musí byť úplná.
1. Endpoint
- URL
- metóda (GET, POST, PUT, DELETE)
- účel endpointu
2. Parametre
- povinné vs nepovinné
- typy
- validácie
- defaultné hodnoty
Bez toho sa nedá endpoint použiť.
3. Request (príklad)
Konkrétny príklad:
- reálny payload
- reálne hodnoty
Nie abstraktný popis.
4. Response (príklad)
- úspešná odpoveď
- štruktúra dát
- význam polí
5. Chybové stavy
Kritická časť, ktorá často chýba:
- stavové kódy (napr. 400, 401, 409, 500)
- význam chyby
- kedy vzniká
- čo má klient urobiť
Tu sa láme použiteľnosť API.
6. Obmedzenia
- rate limiting
- timeouty
- maximálne veľkosti dát
- závislosti na iných systémoch
7. Verziovanie
- verzia API
- kompatibilita
- breaking changes
Bez toho sa integrácie rozbijú pri zmene.
Príklad
Bez dokumentácie:
POST /orders
S dokumentáciou:
- endpoint: POST /orders
- povinné polia: user_id, items
- validácia: items nesmie byť prázdne
- response: order_id, status
- chyba 409: duplicitná objednávka
Zrazu je jasné:
ako endpoint použiť
čo testovať
čo očakávať
Mini checklist
Je jasné, čo endpoint robí?
Sú popísané všetky parametre?
Existuje reálny request príklad?
Existuje reálny response príklad?
Sú uvedené chybové stavy?
Sú popísané obmedzenia?
Je jasná verzia API?
Ak nie, API dokumentácia nie je použiteľná.
Prepojenie na kvalitu a workflow
API dokumentácia nie je len pre vývojára.
Je základ pre:
- testovanie
- integrácie
- support
- onboarding
Pre testera je kľúčová:
Bez nej nevieš:
- pripraviť testovacie dáta
- simulovať chyby
- overiť hraničné stavy
API dokumentácia prepája systém zvnútra s okolím.
Krátke zhrnutie
API dokumentácia nie je zoznam endpointov.
Je to opis toho:
- čo endpoint robí
- čo očakáva
- čo vracia
- čo sa stane pri chybe
Ak chýba:
- integrácie zlyhávajú
- testovanie je slabé
Ak existuje:
- systém je predvídateľný
- tím vie spolupracovať
A to je presne cieľ technickej dokumentácie.