Timp de citire: 9 minute
API-urile fac lumea să se învârtă. Dezvoltatorii folosesc API-uri aproape în fiecare zi – după unele estimări, aceștia petrec peste 10 ore pe săptămână lucrând cu API-uri. Acest lucru acoperă nu numai utilizarea lor, ci și cercetarea, căutarea de asistență pe Google, studierea recenziilor și, bineînțeles, scotocirea în documentație. Cât de clară, ușoară, utilă și susținută este API-ul dvs. determină întreaga experiență a dezvoltatorului (DX) – un răspuns emoțional pe care dezvoltatorii îl au față de produs. În economia API, o experiență excelentă a dezvoltatorului este fundamentală. API-urile care îi ajută pe dezvoltatori să reușească și sunt plăcute de utilizat vor avea tone de utilizatori și se vor ridica deasupra concurenței. Și începe exact din momentul în care aceștia deschid documentația pentru prima dată.
Vizionați acest videoclip pentru o introducere în tehnologia API
Astăzi vom vorbi despre cum să încurajăm o experiență pozitivă a dezvoltatorului în documentația API. Dar, mai întâi, trebuie să înțelegem ce face ca documentația API să fie proastă.
Ce urăsc dezvoltatorii în documentația API
Comunitatea de dezvoltatori este una pasionată. Este în mod specific pasionată de lucrurile care nu le plac. Dacă nu le place o API, de cele mai multe ori este din cauza documentației de doi bani, chiar dacă produsul este de fapt grozav. Iată câteva probleme comune pe care le au dezvoltatorii cu documentația API.
Nu este scrisă folosind un limbaj uman simplu. Aceasta este o problemă comună pentru documentele generate automat sau pentru documentele care sunt neglijate de creatori. Deși multe instrumente de generare a documentației fac o treabă excelentă în ceea ce privește comentarea codului, acestea nu pot înlocui explicațiile reale în limba engleză scrise de un dezvoltator sau un redactor tehnic.
Are foarte puține exemple de cod. Acesta este un alt capăt al spectrului în care explicațiile sunt abundente, dar există exemple minime de cod real.
Este disponibil numai pentru utilizatorii înregistrați. Această manevră nu foarte abilă nu face nimic pentru marketingul dumneavoastră. Nu face decât să îi frustreze pe cei care vor să știe ce face API-ul dvs. înainte de a decide dacă îl doresc (așa cum ar face orice persoană sănătoasă la cap).
Este prea lung/nu poate fi găsit/este inexact/nu a fost actualizat de ani de zile, etc. Crearea unor documente bune este aproape la fel de importantă ca și construirea unui API bun. Pentru că documentele prost scrise sau cele care nu pot fi găsite prin simpla căutare pe Google „Product API” eșuează întregul efort de dezvoltare. Dacă vă interesează, am subliniat deja specificul documentației tehnice în general. Dar documentația API merită un articol dedicat. Deci, cum scrieți o documentație API excelentă?
Adoptați dezvoltarea bazată pe specificații
Dezvoltarea bazată pe specificații (SDD) este similară cu dezvoltarea bazată pe teste, în care scrieți cazuri de testare pentru fiecare caracteristică și apoi scrieți codul care ar trebui să le treacă. În SDD, creați documentația sau cel puțin unele părți ale acesteia în paralel cu construirea unei API, adesea urmând un anumit format de descriere a API-ului numit specificație.
O specificație API este ca un șablon al viitoarei dumneavoastră documentații, limbajul unificat care descrie designul API-ului dumneavoastră, explică modul în care funcționează și ce se așteaptă de la acesta. Există câteva specificații, cum ar fi RAML (RESTful API Modeling Language), OpenAPI (fostul Swagger) și API Blueprint, dar există o tendință de combinare a tuturor specificațiilor sub capota OpenAPI.
Aceste specificații au instrumente de documentare preinstalate care permit scrierea și gestionarea documentelor dumneavoastră. De exemplu, API Console generează automat documente din formatele RAML și OpenAPI și vă ajută să le rulați pe aplicația dvs. web existentă sau ca aplicație independentă.
API Console vă permite să construiți un portal web pentru documentele API din specificațiile RAML și OpenAPI
Sursa: Pawel Psztyc
Alternativă la soluțiile tradiționale de documente API, cum ar fi CMS-urile WordPress sau Drupal, produsele cu specificații API sunt open source, create de comunitatea de dezvoltatori pentru comunitatea de dezvoltatori, au parser în diferite limbaje de programare și suport constant pentru creatori.
Scrieți pentru începători
Există un motiv pentru care documentația tehnică nu este, de obicei, scrisă chiar de către dezvoltatori – este treaba scriitorilor tehnici, experți în traducerea aspectelor tehnice într-un format ușor de citit. Dar chiar și scriitorii tehnici au tendința de a strecura un pic de jargon în text.
Un API, ca orice produs software, este creat pentru un public specific. Dar publicul pentru documentație este vast. Există trei grupuri principale de utilizatori ai documentației:
- dezvoltatorii care vor interacționa în mod intim cu documentația
- factorii de decizie, cum ar fi CTO și arhitecții de soluții, care doresc să determine dacă API-ul dvs. va fi o soluție bună rapid
- observatorii, cum ar fi jurnaliștii, scriitorii tehnici și chiar concurenții care nu vor folosi neapărat API-ul dvs. vreodată.
Și chiar și în cadrul fiecăruia dintre aceste grupuri, există persoane cu aptitudini, roluri și nevoi diferite și toate acestea ar trebui să aibă o experiență pozitivă cu documentele. Cum îi vizați pe toți? Țintindu-i pe cei mai puțin experimentați utilizatori. Așadar, cum scrieți documentația pentru un nou-venit?
Începeți cu oportunitățile mai degrabă decât cu aspectele tehnice. Întâmpinați utilizatorii cu o poveste convingătoare care să le spună cum API-ul dvs. le poate îmbogăți produsul sau le poate face viața dezvoltatorilor de zece ori mai ușoară.
Documentația API-ului Alexa de la Amazon începe prin a explica ce face Alexa și ce beneficii poate aduce clientului
Mostrați de unde să începeți. Documentele API sunt cunoscute pentru faptul că sunt prea copleșitoare și presupun că utilizatorii au o experiență vastă cu API-urile. Secțiunea de început este obligatorie și ar trebui să fie scrisă cu răbdare pentru un potențial utilizator.
Facebook oferă o referință clară pentru începători și urmează pas cu pas procesul de început
Creați instrucțiuni pentru cele mai comune cazuri de utilizare. Probabil că știți deja pentru ce funcții folosesc oamenii API-ul dumneavoastră. Creați secțiuni separate care să le abordeze și includeți acolo exemple de mesaje.
Utilizați un ton conversațional. Comunitatea dezvoltatorilor este relaxată și informală, așa că nu vor aprecia un limbaj corporatist sec, chiar dacă sună mai „profesional”. Documentele bune vorbesc întotdeauna cu oamenii.
Educeți cu privire la instrumentele externe. Dacă API-ul dvs. necesită utilizarea și înțelegerea unor produse și concepte de la terți, cum ar fi OAuth sau npm, includeți link-uri către documentație sau ghiduri de instalare.
Faceți-l ușor de învățat. Documentele API nu sunt instrucțiuni de asamblare IKEA,;ele sunt sursa de învățare. Îmbogățiți-vă documentația cu întrebări frecvente, tutoriale, bloguri și chiar videoclipuri, atunci când este posibil.
Includeți secțiuni must-have
În 2019, SmartBear, dezvoltatorul Swagger, a făcut un sondaj printre dezvoltatorii și utilizatorii de API. Aceștia au aflat care sunt caracteristicile docs considerate cele mai importante în comunitate, oferindu-ne o listă cu secțiunile de documentație must-have pe care dezvoltatorii doresc să le acopere. Vom trece în revistă câteva dintre ele.
SmartBear a chestionat 3.000 de practicieni API
Exemple. Exemplele sunt de obicei prezentate ca bucăți de cod, care sunt suficient de utile, dar care pot fi făcute și mai practice. De exemplu, incluzând o transcriere a câmpurilor, așa cum se face în documentele Medium sau chiar creând o API simulată pentru ca dezvoltatorii să o testeze și să o folosească prin efectuarea de apeluri reale. API-urile simulate pot fi partajate cu ușurință prin intermediul unui URL sau pe GitHub și, dacă sunt realizate la un anumit nivel de detaliu, pot fi folosite chiar și în produsul final.
Statut și erori. Există coduri de stare standard și cele specifice celor din API-ul dumneavoastră. Este o idee bună să includeți toate erorile care pot fi declanșate de API-ul dumneavoastră. Erorile sunt adesea puse pe o pagină dedicată din documentație, dar are sens să duplicăm unele dintre ele direct sub endpoint-ul unde apar cel mai des.
Autentificare. Majoritatea documentelor API încep cu autentificarea și autorizarea. Ar trebui să cuprindă informații despre cum să obțineți o cheie API și cum să autentificați cererile, inclusiv erorile posibile, timpii de expirare a token-urilor și o explicație despre sensibilitatea autentificării (practic, reamintind că cheile nu pot fi partajate și unde pot fi folosite).
Cereri HTTP. Furnizarea de cereri web în HTTP este minimul necesar pentru documentație. De obicei, se presupune că dezvoltatorii vor ști cum să trimită cereri HTTP în limba aleasă de ei, dar, uneori, creatorii de API-uri includ cereri în diferite limbi. Acest lucru se poate face în mod automat prin intermediul instrumentelor de specificații API și al instrumentelor de gestionare a API-urilor, cum ar fi Postman.
Utilizați aspectul standard al industriei
Dacă utilizați un generator de documentație, aspectul este deja decis pentru dumneavoastră. Majoritatea documentelor API arată și se simt la fel. Dacă ați folosit câteva, știți cum să abordați noile documentații. Cu toate acestea, organizarea unor volume mari de date, asigurarea faptului că acestea pot fi găsite și ușor de navigat este o sarcină complexă. Iată câteva caracteristici ale celui mai funcțional layout.
Dispoziție dinamică. Puteți recunoaște un API învechit după documentația sa statică. O singură pagină sau chiar un document PDF nu mai face față în 2020. Documentația dinamică este ușor de parcurs, de actualizat și de marcat.
Conținut lipicios. Nu, bara de navigare nu distrage atenția și nici nu fură spațiu prețios pe ecran. Păstrați întotdeauna conținutul la vedere.
Dispoziție pe trei coloane. Nu este folosit foarte des, acest layout vă permite să aveți o altă coloană în dreapta pentru exemplele de cod. Desigur, acest lucru are sens doar dacă aveți o tonă de text și doriți să evidențiați codul astfel încât utilizatorii să nu fie nevoiți să deruleze înainte și înapoi sau să treacă de la o filă la alta.
Documentele API de la HubSpot folosesc o dispunere pe trei coloane
Utilizați culori contrastante pentru sintaxă. Dezvoltatorii petrec mult timp uitându-se la exemplele dvs. de cod, așa că faceți-le lizibile și separați diferitele componente prin culoare.
Acest exemplu din documentația Graph API de la Facebook arată, de asemenea, cum puteți folosi diferite file pentru a alege între SDK-uri
Salvați starea de defilare. Acesta este un mic detaliu pe care orice dezvoltator îl va aprecia. De asemenea, puteți utiliza linkuri de ancorare pentru a specifica diferite secțiuni ale paginii în cazul în care aceștia copiază URL-ul.
Încurajați feedback-ul. Documentele dvs. sunt principalul dvs. instrument de marketing – dacă oamenii le iubesc, vor folosi API-ul dvs. în detrimentul celui al competitorilor și vor impulsiona comunitatea în jurul acestuia. Obișnuitul mesaj „A fost această pagină utilă?” vă va permite să știți cât de bine răspundeți la întrebările dezvoltatorilor, iar formularul de feedback va fi folosit des atâta timp cât îl veți livra.
Nu vă abandonați documentele
Documentele neactualizate sunt cea mai mare supărare a utilizatorilor API. Aceasta este, de asemenea, una dintre cele mai frecvente greșeli. Dezvoltatorii scriu adesea despre actualizări la câteva zile după ce le-au lansat, limitându-se uneori la câteva fraze. Acest lucru se întâmplă deoarece nu există un proces stabilit pentru actualizarea documentației și nu este responsabilitatea nimănui. Iată cum să asigurați actualizări regulate și utile ale documentelor.
Pregătiți documentele înainte de actualizări. Faceți un pas suplimentar în planul de lansare, nu le lansați înainte de a avea paragrafe bine scrise, detaliate și editate pentru a introduce actualizările.
Îndepărtați regulat datele depreciate. Documentele trebuie să fie revizuite des, cel puțin o dată la câteva luni. Funcțiile de feedback al utilizatorilor vă vor permite să depistați mai devreme inconsecvențele și ar trebui să existe întotdeauna un membru al echipei responsabil pentru revizuirea lor și reacția la actualizări.
Utilizați analiza pentru a îmbunătăți documentele. Analizele API standard vă vor spune ce puncte finale sunt utilizate mai des, astfel încât să vă puteți concentra pe anumite părți ale documentației și să oferiți informații mai utile sau să creați tutoriale dedicate. Monitorizați cazurile de utilizare pentru care sunt folosite API-urile dumneavoastră, deoarece acest lucru vă va permite să lărgiți propunerea de valoare și să actualizați documentația cu mai multe posibilități.
Exemple excelente de documentație API
Există tone de documentații bune pe care să le explorați și din care să învățați. În plus față de exemplele pe care le-am împărtășit de-a lungul articolului, iată alte câteva exemple de care să vă bucurați și pe care să le luați în considerare.
Documentația API Medium
Documentele API Medium nu respectă neapărat toate regulile pe care le-am enumerat astăzi, dar sunt excelente pentru funcționalitatea limitată pe care această API o suportă – postarea și căutarea publicațiilor pe Medium. Ele sunt partajate pe GitHub, au un conținut cu adevărat scurt, dar clar, cu tone de exemple, fiecare dintre ele încheindu-se cu o transcriere a tuturor parametrilor menționați în cod, inclusiv a posibilelor erori. Este remarcabil de simplu, dar de încredere – toate sugestiile pot fi făcute direct pe GitHub, iar documentația este actualizată în mod regulat.
Documentația APIMailchimp
Mailchimp își dă seama că cea mai mare parte a audienței sale sunt profesioniști în marketing și folosește un limbaj care permite chiar și persoanelor non-tehnice să înțeleagă cum să lucreze cu API-urile sale. La prima vedere, fiecare secțiune urmează aceeași structură:
- ce face un punct final și ce le va permite ghidul utilizatorilor să facă
- de ce veți avea nevoie – orice acces sau cont pe care un utilizator trebuie să-l obțină mai întâi
- ce este fiecare funcție cu o descriere text, un exemplu de cod în mai multe limbi și, uneori, capturi de ecran ale interfeței.
Există chiar și un buton de copiere pentru fiecare bucată de cod – un detaliu pe care non-tehnicienii îl vor aprecia cu siguranță.
Documentația API Twilio
Twilio are o documentație API renumită și bună. Deși documentele sunt doar vârful icebergului din tot ajutorul pe care Twilio îl împărtășește – există SDK-uri în mai multe limbi și exemple de aplicații pentru iOS, Android și web. În primul rând, acestea urmează logica celor trei coloane cu codul direct în dreapta ghidului. Cele mai simple acțiuni sunt explicate cu lux de amănunte și cu tone de linkuri pentru informații suplimentare și capturi de ecran. Feedback-ul este, de asemenea, încurajat prin intermediul unui buton „Rate this page” (Evaluați această pagină) și link-uri către echipa de asistență și tag-ul de pe StackOverflow.
Documentația API Spotify
Deși documentația API web a Spotify este foarte tipică, aceștia au o mulțime de informații suplimentare în platforma Spotify for Developers. Există demonstrații pentru funcții de bază, aplicații simulate, exemple live construite folosind API-uri și widget-uri Spotify, wrappers pentru diferite limbaje de programare și, bineînțeles, consola. Consola este, practic, o documentație interactivă în care puteți completa datele dvs. (sau un exemplu) și explora în direct punctele finale. Produsele puternice, împreună cu o bază de cunoștințe puternică, fac din Spotify un partener de încredere cu care dezvoltatorilor le place să lucreze.
Tratați documentația cu grijă
Documentația este singurul punct de contact pe care îl veți avea cu cea mai mare parte a publicului dumneavoastră, așa că trebuie să învățați să comunicați clar prin intermediul acesteia. Cel mai bun sfat în acest caz este să faceți din aceasta o sarcină pentru cineva. Adesea, acesta este un redactor tehnic care știe cum să se adreseze unor audiențe cu abilități diferite, care poate traduce cuvintele dezvoltatorilor în puncte de acțiune, care monitorizează întreținerea și actualizarea în timp util a documentației. Dar gestionarea unei documentații excelente este posibilă chiar și fără un expert în personalul dumneavoastră. Instrumentele de gestionare a API, cum ar fi Swagger UI, Spotlight, Apiary și instrumentele de specificare a documentației au o funcționalitate largă pentru a vă ajuta să realizați documentații pe care dezvoltatorii le vor iubi.
.