Ako navrhnúť chybové hlásenia API?

Ahoj! Ako poskytovateľ API som už nejaký čas v zákopoch pri navrhovaní chybových správ API. Môže sa to zdať ako malá časť celej veci s rozhraním API, ale verte mi, môže to spôsobiť alebo narušiť používateľskú skúsenosť. V tomto blogu sa podelím o niekoľko tipov, ako navrhnúť chybové hlásenia API, ktoré sú skutočne užitočné.

Najprv si povedzme, prečo sú dobré chybové hlásenia dôležité. Keď používateľ pri používaní vášho API narazí na chybu, môže to byť skutočne frustrujúce. Pravdepodobne sú uprostred niečoho dôležitého a zrazu uviazli. Dobre navrhnutá chybová správa môže zmeniť tento frustrujúci moment na príležitosť na učenie. Môže pomôcť používateľovi pochopiť, čo sa pokazilo a ako to opraviť, čo mu ušetrí čas a bolesti hlavy.

Buďte jasní a struční

Najdôležitejšia vec na chybovom hlásení je, že by malo byť jasné. Nechcete používať žargón alebo príliš technický jazyk, ktorému používateľ nemusí rozumieť. Napríklad namiesto „Vyskytol sa problém s kódom stavu nespracovateľnej entity HTTP 422 v dôsledku porušenia obmedzení integrity údajov uvedených v schéme“ môžete povedať „Odoslané údaje nezodpovedajú požadovanému formátu. Skontrolujte svoj vstup a skúste to znova.“

Je tiež dôležité byť stručný. Používatelia nechcú čítať dlhý kľukatý odsek, aby zistili, čo je zlé. Udržujte svoje správy krátke a výstižné. Dobrým pravidlom je zamerať sa na maximálne dve alebo tri vety.

Poskytnite použiteľné informácie

Chybové hlásenie by malo používateľovi nielen povedať, čo sa pokazilo, ale malo by mu tiež poskytnúť predstavu o tom, ako to opraviť. Ak sa napríklad používateľ pokúša získať prístup ku koncovému bodu, ktorý vyžaduje overenie, a neposkytol platné poverenia, chybové hlásenie môže znieť: „Na prístup k tomuto koncovému bodu musíte zadať platné overovacie poverenia. Do hlavičky požiadavky uveďte váš kľúč API.“

Povedzme, že ste poskytovateľom API pre farmaceutického distribútora a máte koncové body pre lieky ako naprCrizotinib,Brigatinib, aHydrát hydrochloridu kapmatinibu. Ak sa používateľ pokúsi získať informácie o lieku, ale použije nesprávne ID lieku, vaša chybová správa môže znieť „ID lieku, ktoré ste poskytli, je nesprávne. Skontrolujte ID a skúste to znova. Správne ID nájdete na našej stránke dokumentácie.“

Použite konzistentné formátovanie

Pri chybových hláseniach je kľúčová konzistentnosť. Použite rovnaký formát pre všetky chybové správy vo vašom rozhraní API. Používateľom to uľahčuje rýchle pochopenie a spracovanie informácií. Môžete napríklad začať všetky svoje chybové hlásenia krátkym popisným názvom tučným písmom, po ktorom bude nasledovať podrobnejšie vysvetlenie.

**Chyba: Neplatný vstup** Zadaný údaj pre pole názvu lieku je neplatný. Mal by to byť reťazec bez špeciálnych znakov. Opravte zadanie a skúste to znova.

Zahrňte kódy chýb

Chybové kódy sú skvelým spôsobom, ako vývojárom poskytnúť podrobnejšie informácie. Tieto kódy môžu použiť na rýchlu identifikáciu a riešenie problémov vo svojich aplikáciách. Uistite sa, že vaše chybové kódy sú jedinečné a ľahko pochopiteľné. Vo svojej dokumentácii API môžete mať samostatnú sekciu, ktorá vysvetľuje, čo jednotlivé chybové kódy znamenajú.

Môžete mať napríklad kód chyby „ERR – 001“ pre „Neplatný kľúč API“ a kód chyby „ERR – 002“ pre „Chýbajúci požadovaný parameter“. Vaša chybová správa by potom mohla znieť niečo ako „Kód chyby: ERR - 001. Zadaný kľúč API je neplatný. Skontrolujte svoj kľúč a skúste to znova.“

Ponúknite informácie o podpore

Niekedy môžu používatelia potrebovať viac pomoci, než akú môže poskytnúť chybové hlásenie. V týchto prípadoch je vhodné zahrnúť informácie o podpore do vašich chybových hlásení. Môže to byť odkaz na vašu stránku podpory, e-mailová adresa alebo fórum, kde môžu používatelia klásť otázky.

Napríklad: „Ak máte problémy aj po vykonaní vyššie uvedených krokov, navštívte našu stránku podpory, kde získate ďalšiu pomoc.“

Otestujte svoje chybové hlásenia

Skôr ako zverejníte svoje rozhranie API, dôkladne otestujte svoje chybové hlásenia. Vyskúšajte rôzne scenáre, ktoré by mohli spôsobiť chyby, a uvidíte, ako správy vyzerajú a pôsobia. Môžete tiež získať spätnú väzbu od iných vývojárov alebo používateľov, aby ste zistili, či sú správy jasné a užitočné.

Zvážte lokalizáciu

Ak vaše API používa globálne publikum, možno by ste mali zvážiť lokalizáciu chybových hlásení. To znamená poskytovanie správ v rôznych jazykoch. Pre používateľov, ktorí nehovoria anglicky, to môže znamenať veľký rozdiel v používateľskej skúsenosti.

Záver

Navrhovanie dobrých chybových správ API je dôležitou súčasťou poskytovateľa API. Tým, že budete jasne, stručne a poskytnete použiteľné informácie, môžete pomôcť svojim používateľom lepšie využívať vaše rozhranie API. Nezabudnite použiť konzistentné formátovanie, zahrnúť chybové kódy, ponúknuť informácie o podpore, otestovať svoje správy a v prípade potreby zvážiť lokalizáciu.

Ak máte záujem o používanie nášho API pre potreby distribúcie liekov, či už je to preCrizotinib,Brigatinib, aleboHydrát hydrochloridu kapmatinibu, radi by sme sa s vami porozprávali. Kontaktujte nás a začnite proces obstarávania a vyjednávania.

Referencie

• Najlepšie postupy dizajnu RESTful API, O'Reilly Media
• Dizajn API pre vývojárov, Google Developers