5 reguli de aur pentru un design API Web excelent

Te-ai întrebat vreodată „la ce se gândeau?” atunci când integrați un serviciu web prin intermediul API-ului său? Dacă nu, ai fost mult mai norocos decât mine.

Orice dezvoltator de software știe cât de ușor este să lași un proiect să se transforme în cod spaghetti, iar API-urile web nu sunt mai puțin predispuse să ducă la un web încurcat. Dar nu trebuie să fie așa. Într-adevăr, este posibil să creați API-uri web grozave pe care oamenii să le folosească cu adevărat și pe care să le creați, de asemenea, cu plăcere. Dar cum? Răspunsul la această întrebare este despre ce este vorba în această postare.

Perspectivă

De cele mai multe ori, atunci când construiți soluții, proiectați pentru utilizatori finali care nu sunt programatori sau care, în general, nu sunt sofisticați din punct de vedere tehnic. Le oferiți o interfață grafică și, dacă v-ați făcut treaba corect, ați cules de la ei o idee destul de bună despre ceea ce au nevoie pentru a face interfața.

Dar dezvoltarea API-ului este diferită. Proiectați o interfață pentru programatori , probabil fără să știți cine sunt aceștia. Și oricine ar fi ei, vor avea sofisticarea tehnică (sau cel puțin vor crede că au sofisticarea tehnică) pentru a sublinia fiecare mic defect al software-ului tău. Este posibil ca utilizatorii dvs. să fie la fel de critici cu privire la API-ul dvs. precum și dvs. pentru ai lor și se vor bucura din plin să îl critice.

Și aici se află o parte din ironie, de altfel. Dacă cineva ar trebui să înțeleagă cum să creeze un API web ușor de utilizat, atunci ești tu . La urma urmei, ești un inginer de software la fel ca utilizatorii API-ului tău, așa că le împărtășești perspectiva. nu-i asa?

Ei bine, deși înțelegeți cu siguranță perspectiva lor, nu le împărtășiți neapărat perspectiva. Când dezvoltați sau îmbunătățiți API - ul, aveți perspectiva unui designer API, în timp ce acesta are perspectiva unui utilizator API .

Designerii API se concentrează de obicei pe întrebări precum „Ce trebuie să facă acest serviciu?” sau „Ce trebuie să ofere acest serviciu?” , în timp ce utilizatorii API sunt concentrați pe „Cum pot folosi acest API pentru a face ceea ce am nevoie?” , sau mai precis, „Cum pot depune un efort minim pentru a obține ceea ce am nevoie din acest API?” .

Aceste întrebări diferite conduc la două perspective foarte diferite. Drept urmare, condiția prealabilă necesară pentru proiectarea unui API grozav este să vă schimbați perspectiva de la cea a designerului API la cea a utilizatorului API. Cu alte cuvinte, pune-ți continuu întrebările pe care le-ai pune în mod natural dacă ai fi propriul tău utilizator. În loc să vă gândiți la ce poate face API-ul dvs., gândiți-vă la diferitele moduri în care poate avea nevoie sau doriți să fie utilizat și apoi concentrați-vă pe a face acele sarcini cât mai ușoare posibil pentru utilizatorii API-ului dvs.

Deși acest lucru poate părea ușor și evident, este uimitor cât de rar par API-urile să fie proiectate în acest fel. Gândește-te la API-urile pe care le-ai întâlnit în cariera ta. Cât de des par să fi fost concepute având în vedere această perspectivă? Designul Web API poate fi o provocare.

Acestea fiind spuse, să continuăm și să vorbim despre cele 5 reguli de aur pentru proiectarea unui API web grozav , și anume:

1. Documentație
2. Stabilitate și consistență
3. Flexibilitate
4. Securitate
5. Ușurința Adopției

Regula 1: Documentare

Documentație. Da, încep de aici.

Urăști documentarea? Ei bine, pot empatiza, dar pune-ți pălăria de „perspectivă utilizator” și voi pariez că singurul lucru pe care îl urăști mai mult decât să scrii documentație este să încerci să folosești un API nedocumentat. Îmi odihnesc cazul.

Concluzia este că, dacă doriți ca cineva să vă folosească API-ul, documentarea este esențială. Pur și simplu trebuie să înțelegi bine. Este primul lucru pe care îl vor vedea utilizatorii, așa că, în anumite privințe, este ca ambalajul cadou. Prezenți-vă bine, iar oamenii sunt mai probabil să vă folosească API-ul și să suporte orice idiosincrazie.

Deci, cum scriem o documentație bună?

Partea relativ ușoară este documentarea metodelor API în sine; adică exemple de cereri și răspunsuri, împreună cu descrieri ale fiecăruia dintre elementele din ambele. Din fericire, există un număr tot mai mare de instrumente software care facilitează și simplifică sarcina de a genera documentație. Sau puteți scrie singur ceva care vă prezintă API-ul, punctele finale și funcțiile și vă generează documentația corespunzătoare.

Dar ceea ce separă documentația excelentă de documentația adecvată este includerea de exemple de utilizare și, în mod ideal, tutoriale. Acesta este ceea ce ajută utilizatorul să înțeleagă API-ul dvs. și de unde să înceapă. Îi orientează și îi ajută să încarce API-ul în creierul lor.

De exemplu, dacă dezvoltatorii Twilio ar enumera fiecare clasă, fiecare metodă și fiecare răspuns posibil la API-ul lor, dar nu s-ar deranja să menționeze că puteți trimite un SMS, urmări un apel sau puteți cumpăra un număr de telefon prin intermediul API-ul lor, ar dura foarte mult timp pentru ca utilizatorul API-ului să găsească acele informații și să le înțeleagă în mod coeziv. Vă puteți imagina că sortați printr-un arbore uriaș de clase și metode fără a înțelege pentru ce au fost folosite, în afară de numele lor? Sună groaznic, nu? Dar exact asta fac atât de mulți furnizori de API, lăsând astfel API-urile lor opace oricui, în afară de ei înșiși. Ghidul pentru dezvoltatori și API Rackspace CloudFiles este un astfel de exemplu; este dificil să vă orientați dacă nu înțelegeți deja ce fac și ce oferă.

Așadar, scrieți tutoriale concise care ajută dezvoltatorul să funcționeze rapid, cu cel puțin un schelet a ceea ce încearcă să facă, apoi îndreptați-le în direcția listei mai detaliate și complet documentate de funcționalități, astfel încât să se poată extinde pe ceea ce au.

Odată ce ați terminat cu documentația, asigurați-vă că validați că are sens pentru alte persoane decât dvs. Trimiteți-l altor dezvoltatori din rețeaua dvs., nu le oferiți alte instrucțiuni decât să le îndreptați către documentație și cereți-le să urmeze un tutorial sau să construiască ceva cu adevărat de bază în aproximativ 15 minute. Dacă nu pot avea o integrare de bază cu API-ul dvs. în 15 minute, aveți mai multă muncă de făcut.

Pentru câteva exemple demne de remarcat de documentație excelentă și detaliată, consultați Twilio, Django și MailChimp. Niciunul dintre aceste produse nu este neapărat cel mai bun de pe piețele lor (deși toate sunt produse bune), totuși se disting prin furnizarea uneia dintre cele mai bune documentații de pe piețele lor, ceea ce cu siguranță a facilitat acceptarea lor largă și cota de piață.

Regula 2: Stabilitate și Consecvență

Dacă ați folosit vreodată API-ul Facebook, știți cât de des își depreciază și rescriu complet API-urile. Indiferent cât de mult ai respecta cultura lor hackerilor sau produsul lor, a lor nu este o perspectivă prietenoasă pentru dezvoltatori. Motivul pentru care au încă succes este pentru că au un miliard de utilizatori, nu pentru că API-ul lor este grozav.

Dar probabil că nu aveți luxul unei baze de utilizatori și a unei cote de piață atât de mamut, așa că va trebui să aveți un API mult mai puțin volatil, menținând versiunile vechi în funcțiune și suportate pentru o perioadă destul de lungă de timp. Poate chiar ani. Așa că, în acest scop, iată câteva sfaturi și trucuri.

Să presupunem, de exemplu, că API-ul dvs. este accesibil prin adresa URL http://myapisite.com/api/widgets și oferă răspunsul în format JSON. Deși acest lucru poate părea în regulă la prima vedere, ce se întâmplă atunci când trebuie să modificați formatul răspunsului JSON? Toți cei care sunt deja integrati cu tine se vor rupe. Hopa!

Așa că faceți puțină planificare înainte și versiuneați API-ul de la început, încorporând în mod explicit un număr de versiune în adresa URL (de exemplu, http://myapisite.com/api/widgets?version=1 sau http://myapisite.com/api/widgets/v1 ), astfel încât oamenii să se poată baza pe versiunea 1 care funcționează și să poată face upgrade la orice versiune ulterioară atunci când sunt gata să facă acest lucru. Dacă trebuie să eliminați treptat o versiune anterioară la un moment dat, mergeți mai departe, dar anunțați suficient și oferiți un fel de plan de tranziție.

O schemă bună de adrese URL va include versiuni majore în adresa URL. Orice modificare a formatului de ieșire sau a tipurilor de date acceptate ar trebui să aibă ca rezultat trecerea la o nouă versiune majoră. În general, este acceptabil să păstrați aceeași versiune dacă tot ceea ce faceți este să adăugați chei sau noduri la ieșire, dar pentru a fi sigur, de fiecare dată când rezultatul se schimbă, creați o versiune.

Pe lângă faptul că sunt stabile în timp, API-urile trebuie să fie coerente intern. Am văzut multe API-uri care modifică numele parametrilor sau metodele de POST-are a datelor, în funcție de punctul final care este utilizat. În schimb, ar trebui să gestionați parametri comuni la nivel global în cadrul API-ului dvs. și să utilizați moștenirea sau o arhitectură partajată pentru a reutiliza aceleași convenții de denumire și gestionarea datelor în mod consecvent în API-ul dvs.

În cele din urmă, trebuie să înregistrați și să publicați un jurnal de modificări pentru a afișa diferențele dintre versiunile API-ului dvs., astfel încât utilizatorii să știe exact cum să facă upgrade.

Regula 3: Flexibilitate

Garbage in, garbage out (GIGO) este o mantră bine cunoscută pentru majoritatea programatorilor. Așa cum este aplicat designului web API, acest principiu ghid tinde să dicteze o abordare destul de rigidă pentru validarea cererii. Sună grozav, nu? Fără mizerie, nicio problemă.

Totuși, ca în toate, trebuie să existe un anumit echilibru. Deoarece nu este posibil să anticipați toate modurile în care utilizatorii vor dori să vă folosească serviciul și, deoarece nu toate platformele client sunt consecvente (adică nu fiecare platformă are suport JSON foarte bun, o bibliotecă OAuth decentă etc.), este bine să aveți cel puțin un anumit grad de flexibilitate sau toleranță în ceea ce privește constrângerile dvs. de intrare și ieșire.

De exemplu, multe API-uri vor accepta o varietate de formate de ieșire, cum ar fi JSON, YAML, XML etc. al., dar va accepta doar specificarea formatului în adresa URL în sine. În spiritul de a rămâne flexibil, puteți permite ca acest lucru să fie specificat și în adresa URL (de exemplu, /api/v1/widgets.json ), sau puteți, de asemenea, să citiți și să recunoașteți un antet HTTP Accept: application/json sau să acceptați un variabilă șir de interogare, cum ar fi ?format=JSON și așa mai departe.

Și în timp ce suntem la asta, de ce să nu permitem ca formatul specificat să nu țină seama de majuscule, astfel încât utilizatorul să poată specifica și ?format=json ? Acesta este un exemplu clasic de modalitate de a atenua frustrarea inutilă pentru utilizatorul API-ului dvs.

Un alt exemplu este permiterea unor moduri diferite de introducere a variabilelor. Deci, așa cum aveți o varietate de formate de ieșire, permiteți și o varietate de formate de intrare (de exemplu, variabile simple POST, JSON, XML etc.). Ar trebui să acceptați cel puțin variabilele POST standard și multe aplicații moderne acceptă și JSON, așa că cele două sunt un loc bun pentru a începe.

Ideea aici este că nu ar trebui să presupuneți că toată lumea vă împărtășește preferințele tehnice. Cu puțină cercetare asupra modului în care funcționează alte API-uri și printr-un dialog cu alți dezvoltatori, puteți aduna alte alternative valoroase care sunt utile și le puteți include în API-ul dvs.

Regula 4: Securitate

Securitatea este, evident, unul dintre cele mai importante lucruri de integrat în serviciul dvs. web, dar atât de mulți dezvoltatori îl fac ridicol de greu de utilizat. În calitate de furnizor de API, ar trebui să oferiți exemple utilizabile despre cum să vă autentificați și să autorizați atunci când vă accesați API-ul. Aceasta nu ar trebui să fie o problemă dificilă la care un utilizator final își petrece ore întregi lucrând. Scopul dvs. fie ca ei să nu fie nevoiți să scrie niciun cod, fie să le ia mai puțin de 5 minute să îl scrie.

Pentru majoritatea API-urilor, prefer o autentificare simplă bazată pe token, în care jetonul este un hash aleatoriu atribuit utilizatorului și acesta îl poate reseta în orice moment dacă a fost furat. Permiteți ca tokenul să fie transmis prin POST sau un antet HTTP. De exemplu, utilizatorul ar putea (și ar trebui) să trimită un token SHA-1 ca variabilă POST sau ca antet într-un format precum „Autorizare: da39a3ee5e6b4b0d3255bfef95601890afd80709”.

De asemenea, alegeți un simbol sigur, nu un identificator numeric scurt. Ceva ireversibil este cel mai bine. De exemplu, este relativ simplu să generați un token SHA în timpul creării utilizatorului și să îl stocați în baza de date. Apoi, puteți pur și simplu să interogați baza de date pentru orice utilizator care se potrivește cu acel simbol. De asemenea, puteți face un token generat cu un identificator unic și o valoare de sare, ceva de genul SHA(User.ID + "abcd123") și apoi să interogați orice utilizator care se potrivește; de exemplu, where TokenFromPost = SHA(User.ID + "abcd123") .

O altă opțiune foarte bună este OAuth 2 + SSL. Oricum ar trebui să utilizați SSL, dar OAuth 2 este destul de simplu de implementat pe partea de server, iar bibliotecile sunt disponibile pentru multe limbaje de programare obișnuite.

Dacă API-ul pe care l-ați creat ar trebui să fie accesibil pe un site web public prin JavaScript, trebuie să vă asigurați, de asemenea, că validați o listă de adrese URL per cont pentru token. În acest fel, nimeni nu poate merge să inspecteze apelurile către API-ul dvs., să fure jetonul de la utilizator și să-l folosească singur.

Iată câteva alte lucruri importante de reținut:

• Funcționalitatea de listare albă. În general, API-urile vă permit să efectuați operațiuni de bază de creare, citire, actualizare și ștergere a datelor. Dar nu doriți să permiteți aceste operațiuni pentru fiecare entitate, așa că asigurați-vă că fiecare are o listă albă de acțiuni permise. Asigurați-vă, de exemplu, că numai utilizatorii autorizați pot rula comenzi precum /user/delete/<id> . În mod similar, toate anteturile utile care sunt trimise în cererea utilizatorului trebuie validate și pe o listă albă. Dacă permiteți antete de tip conținut, verificați că orice trimite utilizatorul se potrivește de fapt cu o listă de tipuri de conținut acceptate. Dacă nu, trimiteți înapoi un mesaj de eroare, cum ar fi un răspuns 406 Nu este acceptabil. Lista albă este importantă, deoarece multe API-uri sunt generate automat sau folosesc o listă neagră, ceea ce înseamnă că trebuie să fii explicit cu privire la ceea ce nu vrei. Cu toate acestea, regula de aur a securității este să începeți cu absolut nimic și să permiteți doar în mod explicit ceea ce doriți.

• Protejați-vă împotriva falsificării cererilor între site-uri (CSRF). Dacă permiteți autentificarea sesiunii sau a modulelor cookie, trebuie să vă asigurați că vă protejați de atacurile CSRF. Proiectul Open Web Application Security (OWASP) oferă îndrumări utile cu privire la modalitățile de a preveni aceste vulnerabilități.

• Validați accesul la resurse. În fiecare solicitare, trebuie să verificați dacă unui utilizator i se permite accesul la articolul specific la care face referire. Deci, dacă aveți un punct final pentru a vizualiza detaliile cardului de credit al unui utilizator (de exemplu, /account/card/view/152423 ), asigurați-vă că ID-ul „152423” face referire la o resursă pe care utilizatorul este într-adevăr autorizat să o acceseze.

• Validați toate intrările. Toate intrările de la un utilizator trebuie analizate în siguranță, de preferință folosind o bibliotecă binecunoscută dacă utilizați intrări complicate, cum ar fi XML sau JSON. Nu-ți construi propriul analizator sau te afli într-o lume de răni.

Regula 5: Ușurința Adopției

Aceasta este într-adevăr cea mai importantă regulă din grup și se bazează pe toate celelalte. După cum am menționat în timpul regulii de documentare, încercați acest lucru cu persoane care sunt noi în API-ul dvs. Asigurați-vă că pot începe să funcționeze cu cel puțin o implementare de bază a API-ului dvs., chiar dacă urmează doar un tutorial, în câteva minute. Cred că 15 minute este un gol bun.

Iată câteva recomandări specifice pentru a ușura și a facilita adoptarea API-ului dvs.:

• Asigurați-vă că oamenii vă pot folosi efectiv API-ul și că funcționează prima dată, de fiecare dată. Rugați-i pe noi să încerce să implementeze ocazional API-ul dvs. pentru a verifica dacă nu este confuz într-un fel la care ați devenit imun.

• Nu te complica. Nu faceți nicio autentificare de lux. Nu faceți o schemă nebună de adrese URL personalizate. Nu reinventați SOAP, sau JSON, sau REST sau orice altceva. Folosiți toate instrumentele pe care le puteți, care au fost deja implementate și sunt acceptate pe scară largă, astfel încât dezvoltatorii trebuie să învețe doar API-ul dvs., nu API + 10 noi tehnologii obscure.

• Furnizați biblioteci specifice limbii pentru a interfața cu serviciul dvs. Există câteva instrumente frumoase pentru a genera automat o bibliotecă pentru dvs., cum ar fi Alpaca sau Apache Thrift. În prezent, Alpaca acceptă Node, PHP, Python și Ruby. Thrift acceptă C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi și multe altele.

• Simplificați orice înscriere necesară. Dacă nu dezvoltați un API open source sau dacă există un proces de înscriere de orice fel, asigurați-vă că, la înscriere, un utilizator este direcționat foarte repede către un tutorial. Și automatizează complet procesul de înscriere, fără a fi nevoie de interacțiune umană din partea ta.

• Oferiți sprijin excelent. Un mare obstacol în calea adopției este lipsa de sprijin. Cum veți gestiona și răspunde la un raport de eroare? Dar documentația neclară? Un utilizator nesofisticat? Forumurile, instrumentele de urmărire a erorilor și asistența prin e-mail sunt începuturi fantastice, dar asigurați-vă că atunci când cineva postează o eroare, o rezolvați cu adevărat. Nimeni nu vrea să vadă un forum de oraș fantomă sau o listă uriașă de erori care nu au fost rezolvate.

Web API Wrap-up

Serviciile web și API-urile lor abundă. Din păcate, marea majoritate sunt greu de utilizat. Motivele variază de la design slab, la lipsa documentației, la volatilitate, la erori nerezolvate sau, în unele cazuri, toate cele de mai sus.

Urmărirea îndrumărilor din această postare vă va ajuta să vă asigurați că API-ul dvs. web este curat, bine documentat și ușor de utilizat. Astfel de API-uri sunt cu adevărat rare și, prin urmare, sunt mult mai probabil să fie adoptate și utilizate pe scară largă.