Čo sa skrýva za odpoveďou API

V predchádzajúcom článku sme sledovali, ako internetový obchod požiada skladový systém o informáciu o produkte. Po odoslaní požiadavky príde odpoveď. Čo však aplikácia z tejto odpovede skutočne zistí?

Nestačí jej vedieť, že server niečo poslal späť. Potrebuje rozpoznať, či požiadavka uspela, aké údaje dostala a či ich dokáže použiť. Ak sa niečo nepodarilo, potrebuje zistiť, o aký problém ide. Pozrime sa na tieto časti postupne.

Odpoveď nie je iba údaj o produkte

Odpoveď webového API má viac častí. HTTP stavový kód stručne oznamuje výsledok požiadavky. Hlavičky môžu obsahovať doplňujúce informácie, napríklad o type vracaného obsahu. Telo odpovede môže niesť samotné údaje o produkte alebo podrobnosti o chybe.

Ak obchod žiada produkt s identifikátorom 123 a skladový systém ho nájde, odpoveď môže obsahovať údaje potrebné na zobrazenie produktu. Ak ho nenájde, odpoveď môže oznámiť práve tento problém. Po niektorých úspešných operáciách nemusí mať odpoveď žiadne telo.

Presný obsah vždy závisí od pravidiel konkrétneho API. Rovnaký stavový kód ešte neznamená, že dve rôzne služby vrátia údaje v rovnakej podobe.

Ako vyzerajú údaje vo formáte JSON

Mnohé webové API posielajú údaje vo formáte JSON. Je to textový zápis, v ktorom sú údaje usporiadané do objektov a zoznamov. Odpoveď s produktom môže vyzerať napríklad takto:

{
  "id": 123,
  "nazov": "Zápisník",
  "cena": 8.5,
  "dostupny": true,
  "sklad": {
    "oznacenie": "BA-1",
    "pocetKusov": 12
  },
  "stitky": ["papiernictvo", "novinka"]
}

Toto je ilustračný príklad, nie predpis pre všetky API. Názvy polí, ich význam aj spôsob zápisu ceny si určuje konkrétna služba.

Vonkajšie zložené zátvorky označujú objekt. V ňom sú polia tvorené názvom a hodnotou, napríklad "nazov": "Zápisník". Pole sklad obsahuje ďalší objekt s vlastnými poľami. Pole stitky obsahuje zoznam dvoch hodnôt, ktorý je uzavretý v hranatých zátvorkách.

Takéto usporiadanie umožňuje jednej odpovedi odovzdať jednoduché údaje aj údaje rozdelené do menších súvisiacich celkov.

Prečo záleží na dátovom type

V JSON môže mať hodnota rôzny dátový typ. V našom príklade je nazov text, id a cena sú čísla, dostupny je pravdivostná hodnota true, sklad je objekt a stitky sú zoznam.

Na prvý pohľad môže ísť o drobné rozdiely, no pre aplikáciu sú dôležité. Hodnota 8.5 je v JSON číslo. Hodnota "8.5" v úvodzovkách je text. Ak chce aplikácia s cenou počítať, potrebuje vedieť, aký typ dostane a čo dané číslo predstavuje. Dokumentácia by mala napríklad určiť aj to, v akej mene je cena a ako sa má zaokrúhľovať.

JSON pozná aj hodnotu null. Tá hovorí, že pri danom poli nie je uvedená bežná hodnota. Sama osebe však nehovorí prečo. Pole môže byť zatiaľ nevyplnené, údaj môže byť neznámy alebo môže mať null iný význam určený konkrétnym API.

Povinné, nepovinné a chýbajúce polia

Predstavme si, že dokumentácia API sľubuje pri každom produkte polia id a nazov, zatiaľ čo pole popis je nepovinné. Aplikácia potom môže s identifikátorom a názvom počítať, ale musí vedieť fungovať aj bez popisu.

Tieto tri situácie nie sú automaticky rovnaké:

{"id": 123, "nazov": "Zápisník"}

Pole popis tu chýba.

{"id": 123, "nazov": "Zápisník", "popis": null}

Pole popis je prítomné, ale má hodnotu null.

{"id": 123, "nazov": "Zápisník", "popis": ""}

Pole popis je prítomné a obsahuje prázdny text.

Či tieto podoby znamenajú to isté alebo niečo odlišné, neurčuje samotný JSON. Musí to vysvetliť konkrétne API. Ak aplikácia rozdiel prehliadne, môže používateľovi zobraziť nesprávny údaj alebo pri spracovaní odpovede zlyhať.

Rovnako treba rozlišovať medzi údajom, ktorý dokumentácia označuje ako povinný, a údajom, ktorý sa iba náhodou nachádzal vo všetkých doteraz videných príkladoch. Jeden príklad odpovede ešte nie je úplným opisom pravidiel.

Čo hovoria HTTP stavové kódy

Stavový kód je trojmiestne číslo, ktoré oznamuje výsledok HTTP požiadavky. Kódy začínajúce číslicou 2 označujú úspešné spracovanie. Kódy začínajúce číslicou 4 súvisia s problémom v požiadavke alebo s tým, že ju server nemôže splniť. Kódy začínajúce číslicou 5 označujú chybu na strane servera.

Pri práci s API sa často stretneme s týmito kódmi:

  • 200 OK znamená, že požiadavka uspela. Pri načítaní produktu môže telo odpovede obsahovať jeho údaje.
  • 201 Created znamená, že bol vytvorený nový zdroj, napríklad produkt po úspešnej požiadavke na pridanie.
  • 204 No Content znamená úspech bez tela odpovede. Aplikácia po ňom nemá očakávať JSON s údajmi.
  • 400 Bad Request označuje požiadavku, ktorú server nedokáže spracovať pre problém na strane klienta, napríklad chybný zápis.
  • 401 Unauthorized znamená, že požiadavka nemá platné overenie identity požadované pre daný zdroj.
  • 403 Forbidden znamená, že server požiadavke rozumie, ale odmieta ju splniť. Napríklad používateľ nemá potrebné oprávnenie.
  • 404 Not Found znamená, že server nenašiel požadovaný zdroj, napríklad produkt s daným identifikátorom.
  • 500 Internal Server Error označuje neočakávaný problém na strane servera, pre ktorý požiadavku nedokázal splniť.

Tieto kódy majú všeobecný význam. Samotný kód však nemusí povedať, ktoré pole v požiadavke bolo chybné alebo čo má používateľ urobiť. Na to môže slúžiť telo chybovej odpovede. Zoznam HTTP stavových kódov s popisom.

Čo môže obsahovať chybová odpoveď

Obchod požiada skladový systém o produkt 999, ktorý neexistuje. Server môže vrátiť stav 404 Not Found a k nemu napríklad takéto telo odpovede:

{
  "kod": "PRODUKT_NENAJDENY",
  "sprava": "Produkt s identifikátorom 999 neexistuje."
}

Stavový kód 404 oznamuje všeobecný výsledok. Polia kod a sprava v tomto príklade spresňujú, čo sa stalo v danej aplikácii. Názvy týchto polí nie sú univerzálne. Iné API môže použiť odlišnú štruktúru alebo nemusí poslať podrobnú správu vôbec.

Chybová správa pomáha aplikácii rozhodnúť, čo ďalej. Pri neexistujúcom produkte môže zobraziť oznam, že položka už nie je dostupná. Pri chybnom vstupe môže používateľa vyzvať na opravu. Pri chybe servera môže ponúknuť opakovanie neskôr.

Aplikácia by však nemala stavať celé rozhodovanie iba na voľne formulovanom texte správy. Ten sa môže zmeniť alebo byť preložený. Ak API poskytuje stabilný kód chyby určený na spracovanie programom, je vhodnejšie riadiť sa jeho zdokumentovaným významom.

Ako čítať odpoveď ako celok

Predstavme si, že obchod očakáva údaje o produkte. Pri odpovedi 200 OK môže pokračovať kontrolou tela: je v ňom JSON, obsahuje očakávaný identifikátor a názov a majú polia správne typy? Až potom vie údaje bezpečne použiť na zobrazenie detailu.

Pri odpovedi 204 No Content je požiadavka úspešná, no telo chýba podľa významu tohto kódu. Pokus čítať z neho názov produktu by bol chybou. Pri 404 Not Found má aplikácia spracovať nenájdený produkt, nie pokračovať, akoby dostala platný záznam. Pri 500 Internal Server Error vie, že problém nastal na strane služby, hoci nemusí poznať jeho presnú príčinu.

Na správne spracovanie preto treba čítať odpoveď v súvislostiach: stavový kód, prípadné hlavičky, telo odpovede a pravidlá uvedené v dokumentácii API. Jediné pole ani jediný príklad odpovede nedávajú úplný obraz o tom, čo sa môže stať.

API neposiela iba údaje. Odpoveďou zároveň oznamuje, ako požiadavka dopadla. Keď aplikácia rozumie obom týmto častiam, dokáže používateľovi zobraziť správny výsledok aj primerane reagovať na chybu.

Predchádzajúci článok: Čo je API a ako spolu aplikácie komunikujú

Pridajte Komentár

Vaša e-mailová adresa nebude zverejnená. Vyžadované polia sú označené *

Návrat hore