Hogyan tervezzünk API hibaüzeneteket?

Szia! API-szolgáltatóként már jó ideje az API-hibaüzenetek tervezésével foglalkozom. Úgy tűnhet, hogy ez egy kis része az egész API-nak, de higgyen nekem, javíthatja vagy megtörheti a felhasználói élményt. Ebben a blogban megosztok néhány tippet az API-hibaüzenetek megtervezéséhez, amelyek valóban hasznosak.

Először is beszéljünk arról, miért számítanak a jó hibaüzenetek. Ha egy felhasználó hibát észlel az API használata közben, az nagyon frusztráló lehet. Valószínűleg valami fontos dolog kellős közepén vannak, és hirtelen elakadnak. Egy jól megtervezett hibaüzenet tanulási lehetőséggé változtathatja ezt a frusztráló pillanatot. Segíthet a felhasználónak megérteni, mi hibázott, és hogyan javíthatja ki, így időt és fejfájást takaríthat meg.

Legyen világos és tömör

A hibaüzenettel kapcsolatos legfontosabb dolog az, hogy egyértelmű legyen. Ne használjon szakzsargont vagy túlzottan szaknyelvet, amelyet a felhasználó esetleg nem ért. Például ahelyett, hogy azt mondaná, hogy „Probléma lépett fel a HTTP 422 feldolgozhatatlan entitás állapotkódjával a sémában meghatározott adatintegritási megszorítások megsértése miatt”, azt mondhatja, hogy „Az elküldött adatok nem egyeznek a szükséges formátummal. Ellenőrizze a bevitt adatokat, és próbálja újra”.

Az is fontos, hogy tömör legyen. A felhasználók nem akarnak egy hosszú, kanyargós bekezdést elolvasni, hogy rájöjjenek, mi a hiba. Üzenete legyen rövid és lényegre törő. Jó ökölszabály, hogy legfeljebb két-három mondatra törekedj.

Adjon cselekvésre alkalmas információkat

A hibaüzenetnek nemcsak arról kell tájékoztatnia a felhasználót, hogy mi történt, hanem ötleteket kell adnia a hiba kijavítására is. Például, ha a felhasználó egy hitelesítést igénylő végponthoz próbál hozzáférni, és nem adott meg érvényes hitelesítési adatokat, a hibaüzenet a következő lehet: "A végpont eléréséhez érvényes hitelesítési adatokat kell megadnia. Kérjük, adja meg API-kulcsát a kérelem fejlécében."

Tegyük fel, hogy Ön egy gyógyszerforgalmazó API-szolgáltatója, és olyan végpontokkal rendelkezik, mint példáulKrizotinib,Brigatinib, ésCapmatinib-hidroklorid-hidrát. Ha egy felhasználó megpróbál információt szerezni egy kábítószerről, de helytelen gyógyszerazonosítót használ, a hibaüzenet a következő lehet: "Az Ön által megadott gyógyszerazonosító helytelen. Kérjük, ellenőrizze az azonosítót, és próbálja újra. A megfelelő azonosítókat a dokumentációs oldalunkon találja."

Használjon konzisztens formázást

A következetesség kulcsfontosságú, ha hibaüzenetekről van szó. Használja ugyanazt a formátumot az összes hibaüzenethez az API-ban. Ez megkönnyíti a felhasználók számára az információk gyors megértését és feldolgozását. Például kezdheti az összes hibaüzenetet egy rövid, leíró félkövér címmel, amelyet egy részletesebb magyarázat követ.

**Hiba: Érvénytelen bevitel** A gyógyszernév mezőben megadott bevitel nem érvényes. Egy karakterláncnak kell lennie speciális karakterek nélkül. Kérjük, javítsa a bevitelt, és próbálja újra.

Tartalmazza a hibakódokat

A hibakódok nagyszerű módja annak, hogy részletesebb információkat nyújtsanak a fejlesztőknek. Ezekkel a kódokkal gyorsan azonosíthatják és elháríthatják alkalmazásaik problémáit. Győződjön meg arról, hogy a hibakódok egyediek és könnyen érthetők. Az API-dokumentációban külön szakaszt találhat, amely elmagyarázza az egyes hibakódok jelentését.

Például előfordulhat, hogy az "ERR - 001" hibakód az "Érvénytelen API kulcs" és az "ERR - 002" hibakód a "Hiányzó szükséges paraméter". A hibaüzenet ilyen jellegű lehet: "Hibakód: ERR - 001. Az Ön által megadott API-kulcs érvénytelen. Ellenőrizze a kulcsot, és próbálja újra."

Támogatási információk felajánlása

Néha a felhasználóknak több segítségre van szükségük, mint amit a hibaüzenet nyújthat. Ilyen esetekben célszerű támogatási információkat feltüntetni a hibaüzenetekben. Ez lehet egy hivatkozás az Ön támogatási oldalára, egy e-mail cím vagy egy fórum, ahol a felhasználók kérdéseket tehetnek fel.

Például: "Ha a fenti lépések végrehajtása után továbbra is problémái vannak, további segítségért keresse fel támogatási oldalunkat."

Tesztelje a hibaüzeneteket

Mielőtt közzétenné az API-t, alaposan ellenőrizze a hibaüzeneteket. Próbáljon ki különböző forgatókönyveket, amelyek hibákat idézhetnek elő, és nézze meg, hogyan néznek ki az üzenetek. Más fejlesztőktől vagy felhasználóktól is kérhet visszajelzést, hogy megtudja, az üzenetek világosak és hasznosak-e.

Fontolja meg a lokalizációt

Ha az API-ját globális közönség használja, érdemes megfontolni a hibaüzenetek lokalizálását. Ez azt jelenti, hogy az üzeneteket különböző nyelveken kell megadni. Nagy változást hozhat a nem angolul beszélők felhasználói élményében.

Következtetés

A jó API hibaüzenetek tervezése fontos része az API-szolgáltatónak. Azáltal, hogy világos, tömör és használható információkat ad meg, segíthet felhasználóinak abban, hogy jobb élményben részesüljenek az API használata során. Ne felejtsen el következetes formázást használni, adjon meg hibakódokat, kínáljon támogatási információkat, tesztelje az üzeneteket, és szükség esetén fontolja meg a lokalizációt.

Ha érdekli, hogy az API-nkat gyógyszerforgalmazási igényeihez használja, akár azKrizotinib,Brigatinib, vagyCapmatinib-hidroklorid-hidrát, szívesen beszélgetnénk veled. Forduljon hozzánk a beszerzési és tárgyalási folyamat elindításához.

Hivatkozások

• RESTful API Design Best Practices, O'Reilly Media
• API Design for Developers, Google Developers