API-urile au devenit foarte importante într-o lume dominată de aplicaţii interconectate. API-urile au evoluat mult în ultimii ani, în special datorită standardelor JSON + REST. Însă mai există o subtilitate pe care trebuie să o iei în calcul:
Acronimul reflectă acest aspect: Interfaţă programabilă a aplicaţiei. Interfaţă pentru ce? Pentru alte sisteme software. Dar cine scrie aceste sisteme? Programatorii. Aşadar, API-ul este într-adevăr o interfaţă cu utilizatorul pentru programatorii ce îl folosesc.
Dat fiind că API-urile sunt interfeţe cu utilizatorul, se impune aplicarea principiilor şi tehnicilor UX pentru a fi folosite mai uşor. Iată cinci dintre ele.
Cea mai bună metodă în acest sens este punerea la dispoziţie a unor mostre de cod gata de utilizare pentru cele mai comune limbaje de programare. La data scrierii acestui articol, recomandăm mostre de cod cel puţin pentru Java, C#, Javascript, ruby, python, PHP. Aceste mostre de cod trebuie să ofere suficiente informaţii pentru a te conecta la API, pentru a te autentifica şi a implementa cele mai frecvente scenarii. Mai multe informaţii la punctul 4.
Pentru a fi cât mai simplu, mostra de cod ar trebui să conțină tokenul de autentificare a utilizatorului logat. Şi anume, în locul:
client.call(<YOUR_TOKEN>);se poate afişa:
client.call("ASFasfduoiw2343vc");Cele mai bune API-uri sunt foarte uşor de învăţat. Redactarea unei documentaţii cuprinzătoare nu este suficientă. Utilizatorii nu au timp să parcurgă sute de pagini de manuale, dat fiind că au termene limită. Aşadar, pot ei deduce modul de acţiune într-un scenariu cu care nu s-au mai confruntat?
Multe API-uri arată că acest lucru este posibil. Secretul constă în consistenţă.
API-ul Highrise este un exemplu excelent de consistenţă. Highrise este un CRM SaaS simplu, dar foarte util. Asigură consistenţă pe multe nivele:
Accesul REST la toate resursele;
Structură similară de răspuns la cereri de resurse similare ;
Denumiri consecvente ale câmpurilor în răspuns;
Răspuns în format XML cât şi JSON, la cererea utilizatorului;
După ce aţi învăţat cum să folosiţi o anumită resursă în API-ul Highrise, celelalte vin natural. Doriţi o listă a persoanelor?
GET /people.xml
<people>
<person>
...
</person>
<person>
...
</person>
</people>
Doriţi o listă a companiilor?
GET /companies.xml
<companies>
<company>
...
</company>
<company>
...
</company>
</companies>Răspunsul pentru companii şi persoane conţine câmpuri pentru informaţiile de contact, structurate exact în acelaşi mod:
<contact-data>
<email-addresses>
<email-address>
<id type="integer">1
</id>
<address>
corporate@example.com
</address>
<location>Work</location>
</email-address>
</email-addresses>
<phone-numbers>
<phone-number>
<id type="integer">2</id>
<number>555-555-5555</number>
<location>Work</location>
</phone-number>
<phone-number>
<id type="integer">3</id>
<number>555-666-6667</number>
<location>Fax</location>
</phone-number>
</phone-numbers>
</contact-data>API-ul Highrise este un studiu de caz foarte interesant din perspectiva învățării și consecvenţei. Invităm cititorii să-l încerce şi să se inspire din modelul său.
Una dintre cele mai enervante situaţii cu care se confruntă programatorii este atunci când au scris un cod care ar trebui să funcţioneze şi totuşi nu funcţionează dintr-un motiv oarecare.
Când au de - a face cu un API, acest lucru este cu atât mai neplăcut. De regulă, singurele modalităţi de rezolvare a problemei sunt analiza documentaţiei şi solicitarea asistenţei tehnice. Astfel utilizatorii pierd timp preţios.
API-urile bune au comportament consecvent. Returnează acelaşi cod de eroare pentru aceeaşi eroare. Gestionează cât de multe erori posibil. Comunică un mesaj util programatorului pentru a înţelege ceea ce este greşit şi cum să remedieze. Pentru situaţii mai ciudate, ele au un index cu probleme şi soluţii uşor de navigat. În plus, asigură asistenţă utilă şi rapidă la nevoie.
Există şi modalităţi de evitare a multora dintre aceste probleme: proiectarea API-ului pentru a evita pe cât posibil apariţia erorilor. Dacă sunt mulţi utilizatori care fac aceeaşi greşeală, îmbunătăţiţi modelul astfel încât să nu se mai întâmple. Nu numai ca va spori satisfacţia utilizatorului, dar va fi redusă şi activitatea de asistenţă. Toţi au de câştigat.
Pentru că API-urile sunt interfeţe cu utilizatorii, trebuie să înţelegeţi scenariile şi să le testaţi cu teste de utilizare. Să luăm de exemplu un CRM precum Highrise. Scenariile obişnuite includ:
Obţinerea unei liste cu toate contactele cu anumite criterii, pentru a fi folosite la ceva (ex. întocmire facturi);
Întocmirea unui raport de activitate dintr-o anumită perioadă (ex. raport pe 3 luni cu toate tranzacţiile, câştigate, suspendate, pierdute sau durata medie de la demararea unei tranzacţii până la momentul la care înregistrează câştig sau pierdere);
Aceste scenarii pot fi împărţite pe rând în mai mulţi paşi, generând etape de implementare simple. Fiecare etapă de acest tip se poate testa prin:
Implementarea unui API (poate fi şi o implementare dummy);
Solicitarea programatorilor care nu l-au folosit niciodată de a pune în aplicare una dintre acele etape sau un scenariu complet;
Aceste informaţii sunt folosite pentru a facilita şi îmbunătăţi designul API-ului.
Există două modalităţi de dezvoltare a unui API:
De jos în sus: implementăm un API şi vedem dacă funcţionează.
Recomandăm metoda a doua pentru cele mai bune rezultate. În loc să se formuleze ipoteze despre API, porniţi de la punctul de vedere al utilizatorului. Scrie codul pe care ai vrea să-l scrii pentru a utiliza API-ul şi după ce ești mulţumit, începe să-l implementezi. Codul client se poate transforma în teste funcţionale pentru API şi în mostre de cod pentru documentare. Este un câştig pe toate fronturile.
V-am prezentat cinci recomandări pentru o experienţă remarcabilă a unui programator care foloseşte API-uri. Fiecare dintre acestea este inspirată de cel puţin unul din cele cinci principii de usability: uşurinţă de învăţare, eficienţă, uşurinţă de memorare, evitare greşeli, satisfacţie. În epoca SaaS şi a aplicaţiilor mobile, vor fi remarcate echipele care ating un nivel excelent în acest sens. Succes!
PS: Nu uitaţi să contactaţi autorii pentru observaţii și întrebări sau în cazul în Mulţumim!
de Ovidiu Mățan
de Ovidiu Mățan
de Laura Sima
