Kako dizajnirati API poruke o grešci?

Hej tamo! Kao dobavljač API-ja, već duže vrijeme sam u rovovima dizajniranja poruka o greškama API-ja. Možda se čini kao mali dio cijele stvari s API-jem, ali vjerujte mi, može poboljšati ili pokvariti korisničko iskustvo. U ovom blogu ću podijeliti nekoliko savjeta o tome kako dizajnirati API poruke o greškama koje su zapravo korisne.

Prvo, hajde da razgovaramo o tome zašto su dobre poruke o grešci važne. Kada korisnik naiđe na grešku dok koristi vaš API, to može biti stvarno frustrirajuće. Vjerovatno su usred nečega važnog i odjednom su zaglavili. Dobro osmišljena poruka o grešci može taj frustrirajući trenutak pretvoriti u priliku za učenje. Može pomoći korisniku da shvati šta je pošlo po zlu i kako to popraviti, štedeći im vrijeme i glavobolje.

Budite jasni i koncizni

Najvažnija stvar u vezi sa porukom o grešci je da treba da bude jasna. Ne želite da koristite žargon ili preterano tehnički jezik koji korisnik možda ne razume. Na primjer, umjesto da kažete "Postojao je problem sa statusnim kodom HTTP 422 neobradivog entiteta zbog kršenja ograničenja integriteta podataka navedenih u šemi", mogli biste reći "Podaci koje ste poslali ne odgovaraju traženom formatu. Molimo provjerite svoj unos i pokušajte ponovo."

Takođe je ključno biti koncizan. Korisnici ne žele da čitaju dugačak, krivudavi paragraf da bi shvatili šta nije u redu. Neka vaše poruke budu kratke i jasne. Dobro pravilo je da ciljate ne više od dvije ili tri rečenice.

Obezbedite informacije koje su korisne

Poruka o grešci ne samo da bi trebalo da kaže korisniku šta je pošlo po zlu, već i da mu da ideju kako da to popravi. Na primjer, ako korisnik pokušava pristupiti krajnjoj točki koja zahtijeva autentifikaciju, a nisu dali valjane vjerodajnice, poruka o grešci bi mogla glasiti "Morate dati važeće vjerodajnice za autentifikaciju da biste pristupili ovoj krajnjoj točki. Molimo uključite svoj API ključ u zaglavlje zahtjeva."

Recimo da ste dobavljač API-ja za farmaceutskog distributera i imate krajnje tačke za lijekove kao što jeCrizotinib,Brigatinib, iKapmatinib hidroklorid hidrat. Ako korisnik pokuša dobiti informacije o lijeku, ali koristi netačan ID lijeka, vaša poruka o grešci može glasiti "ID lijeka koji ste naveli je netačan. Provjerite ID i pokušajte ponovo. Ispravne ID-ove možete pronaći na našoj stranici sa dokumentacijom."

Koristite dosljedno formatiranje

Dosljednost je ključna kada su u pitanju poruke o greškama. Koristite isti format za sve poruke o grešci u vašem API-ju. To korisnicima olakšava brzo razumijevanje i obradu informacija. Na primjer, sve poruke o grešci možete započeti kratkim, opisnim naslovom podebljanim, nakon čega slijedi detaljnije objašnjenje.

**Greška: Nevažeći unos** Unos koji ste dali za polje naziva lijeka nije važeći. To bi trebao biti niz bez posebnih znakova. Ispravite unos i pokušajte ponovo.

Uključite kodove grešaka

Kodovi grešaka su odličan način za pružanje detaljnijih informacija programerima. Oni mogu koristiti ove kodove za brzo prepoznavanje i rješavanje problema u svojim aplikacijama. Provjerite jesu li vaši kodovi grešaka jedinstveni i lako razumljivi. Možete imati poseban odjeljak u svojoj API dokumentaciji koji objašnjava šta svaki kod greške znači.

Na primjer, mogli biste imati kod greške "ERR - 001" za "Nevažeći API ključ" i kod greške "ERR - 002" za "Nedostaje potreban parametar". Vaša poruka o grešci bi tada mogla reći nešto poput "Kôd greške: ERR - 001. API ključ koji ste naveli je nevažeći. Provjerite svoj ključ i pokušajte ponovo."

Ponudite informacije o podršci

Ponekad će korisnicima možda trebati više pomoći od onoga što poruka o grešci može pružiti. U ovim slučajevima, dobra je ideja uključiti informacije o podršci u poruke o grešci. Ovo može biti veza do vaše stranice za podršku, adresa e-pošte ili forum na kojem korisnici mogu postavljati pitanja.

Na primjer, "Ako i dalje imate problema nakon što slijedite gore navedene korake, posjetite našu stranicu podrške za dodatnu pomoć."

Testirajte svoje poruke o greškama

Prije nego što svoj API objavite javnosti, obavezno temeljito testirajte svoje poruke o greškama. Isprobajte različite scenarije koji bi mogli izazvati greške i pogledajte kako poruke izgledaju i osjećaju se. Također možete dobiti povratne informacije od drugih programera ili korisnika da vidite da li su poruke jasne i korisne.

Razmotrite lokalizaciju

Ako vaš API koristi globalna publika, možda biste trebali razmisliti o lokalizaciji vaših poruka o grešci. To znači pružanje poruka na različitim jezicima. To može napraviti veliku razliku u korisničkom iskustvu za one koji ne govore engleski.

Zaključak

Dizajniranje dobrih poruka o greškama u API-ju važan je dio provajdera API-ja. Ako budete jasni, koncizni i pružajući informacije koje su korisne, možete pomoći svojim korisnicima da imaju bolje iskustvo kada koriste vaš API. Ne zaboravite koristiti dosljedno formatiranje, uključiti kodove grešaka, ponuditi informacije o podršci, testirati svoje poruke i razmotriti lokalizaciju ako je potrebno.

Ako ste zainteresirani za korištenje našeg API-ja za potrebe vaše farmaceutske distribucije, bilo da je zaCrizotinib,Brigatinib, iliKapmatinib hidroklorid hidrat, voljeli bismo da popričamo s vama. Obratite nam se za početak procesa nabavke i pregovora.

Reference

• RESTful API dizajn najbolje prakse, O'Reilly Media
• API dizajn za programere, Google Developers