10 Componente importante ale documentației API

Mai multe organizații folosesc puterea API-urilor pentru a-și optimiza afacerea. API-urile au devenit o modalitate de a debloca valoare și de a oferi un serviciu suplimentar.

În ciuda popularității lor generale, nu orice API este un succes. Adoptarea și utilizarea unui API determină în mare măsură succesul acestuia. Pentru a crește gradul de adopție, API-ul dvs. trebuie să fie ușor de găsit și de utilizat.

Cel mai bun mod de a face acest lucru este documentarea API-ului în detaliu. Aceasta include detalierea componentelor critice pentru a le face mai ușor de înțeles. Aflați câteva dintre componentele pe care ar trebui să le includeți în documentația API.

Ce este documentația API?

Documentația API este conținut tehnic care descrie un API în detaliu. Este un manual care conține toate informațiile necesare pentru a lucra cu API-ul. Documentul acoperă ciclul de viață API și instrucțiuni privind integrarea și utilizarea componentelor sale.

Documentația API acoperă descrieri de resurse, puncte finale, metode, solicitări și exemple de răspuns. De asemenea, poate include ghiduri practice și tutoriale care arată utilizatorilor cum să-l integreze. Explorarea fiecărei secțiuni oferă utilizatorilor o înțelegere solidă a integrării și utilizării API-ului.

Editori precum Google Docs au fost cândva folosiți pe scară largă pentru documentarea profesională API. În prezent, există instrumente mai avansate precum Document 360, Confluence și GitHub Pages. Aceste instrumente ajută la integrarea textului și a codului pentru fluxuri de lucru mai ușoare.

1. Prezentare generală și scopul API-ului

Primul pas în documentarea unui API este să informeze utilizatorii despre ce este vorba. Includeți informații despre tipul de resurse pe care le oferă. API-urile au de obicei diverse resurse pe care le returnează, astfel încât utilizatorul poate solicita ceea ce are nevoie.

Descrierea este scurtă, de obicei una până la trei propoziții care descriu resursa. Descrieți resursa disponibilă, punctele finale și metodele atașate fiecărui punct final. În calitate de dezvoltator API, descrieți cel mai bine componentele, funcționalitatea și cazul de utilizare.

Iată un exemplu de descriere a API-ului Airbnb:

2. Metode de autentificare și autorizare

API-urile gestionează mii de solicitări și cantități enorme de date. Autentificarea este una dintre modalitățile de a vă asigura că datele API-ului dvs. și utilizatorii sunt protejate de hackeri. Autentificarea API verifică identitatea unui utilizator și le oferă acces la resurse.

Există mai multe modalități de a asigura securitatea punctului final. Majoritatea API-urilor folosesc o cheie API. Acesta este un șir de caractere pe care un utilizator le poate genera de pe site și le poate folosi pentru autentificare.

Documentația API ar trebui să ghideze utilizatorii cu privire la modul de autentificare și autorizare a identității acestora. Următoarea diagramă prezintă informații de autentificare Twitter API.

3. Puncte finale, modele URI și metode HTTP

În această secțiune, demonstrează cum să accesezi resursa. Punctele finale arată doar sfârșitul căii, de unde și numele lor. Ele arată accesul la resursă și metode HTTP punctul final interacționează cu, și anume GET, POST sau DELETE.

O resursă are probabil o varietate de puncte finale. Fiecare cu o cale și o metodă diferită. Punctele finale au de obicei scurte descrieri ale scopului lor și un model URL.

Următorul exemplu de cod arată un punct final de utilizator GET pe Instagram.

Da-mi? fields={fields}&access_token={access-token}

4. Formate de cerere și răspuns

Trebuie să documentați formatele de solicitare și răspuns, astfel încât utilizatorul să știe la ce să se aștepte. Solicitarea este o adresă URL de la un client care solicită o resursă, în timp ce răspunsul este feedback de la server.

Mai jos este un exemplu de solicitare pe care o puteți trimite către API-ul LinkedIn.

OBȚINE https://api.linkedin.com/v2/{service}/1234

Și iată un exemplu de răspuns pe care îl poate returna:

{
 „id”: 1234,
 "relatedEntity": "urn: li: relatedEntity: 6789"
}

5. Parametri și anteturi

De asemenea, ar trebui să documentați parametrii punctelor finale, care sunt opțiuni pe care le puteți transmite acestora. Parametrii pot fi un ID sau un număr care specifică cantitatea sau tipul de date returnate ca răspuns.

Există diferite tipuri de parametri, inclusiv antet, cale și parametri șir de interogare. Punctele finale pot conține diferite tipuri de parametri.

Puteți include unii parametri ca antete de solicitare HTTP. De obicei, acestea sunt în scopuri de autentificare, cum ar fi o cheie API. Iată un exemplu de antet cu chei API:

anteturi: {
 „X-RapidAPI-Key”: „fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635”,
 „X-RapidAPI-Host”: „wft-geo-db.p.rapidapi.com”
}

Includeți parametrii căii în corpul punctului final chiar pe adresa URL. Acestea arată utilizatorului cum și unde să plaseze parametrii și cum va apărea răspunsul. Cuvintele din acolade sunt parametri.

De asemenea, puteți utiliza două puncte sau altă sintaxă pentru a reprezenta parametrii căii.

/service/myresource/user/{user}/bicycles/{bicycleId}

Cu parametrii de interogare, trebuie să plasați un semn de întrebare (?) înaintea interogării pe un punct final. Separați fiecare parametru după aceea cu un ampersand (&). Microsoft are o documentație bună despre API-ul Graph.

6. Codurile de eroare și tratarea erorilor

Uneori, solicitările HTTP eșuează, ceea ce poate lăsa un utilizator confuz. Includeți codurile de eroare așteptate în documentație pentru a ajuta utilizatorii să înțeleagă erorile.

LinkedIn oferă coduri de eroare HTTP standard pentru tratarea erorilor:

7. Exemple de fragmente de cod

Fragmentele de cod sunt părți esențiale ale documentației dvs. Ele arată utilizatorilor cum să integreze API-ul în diferite limbi și formate. Includeți modul de instalare și integrare a SDK-urilor (kituri de dezvoltare software) în diferite limbi în documentație.

RapidAPI are exemple bune de fragmente de cod pentru dezvoltatori:

9. Versiunile API și jurnalele modificărilor

Versiune API este o parte esențială a Design API. Acesta asigură furnizarea de servicii neîntrerupte utilizatorilor dumneavoastră. Versiunile poate îmbunătăți API-ul cu versiuni noi, fără a afecta aplicațiile client.

Utilizatorii pot continua să folosească versiuni mai vechi sau pot migra la cele avansate în timp. Dacă există noi modificări ale jurnalelor, includeți-le în documentație, astfel încât utilizatorii să fie conștienți.

Microsoft Graph API are jurnalele de modificări bine documentate:

În cele din urmă, includeți contacte importante în documentație pentru asistență și feedback. Acestea asigură că utilizatorii vă pot contacta cu rapoarte de eroare și informații despre cum să îmbunătățiți API-ul.

Valoarea documentației API

Dacă construiți un API pentru valoare comercială, consumul îi determină succesul. Și pentru ca utilizatorii să vă consume API-ul, trebuie să îl înțeleagă.

Documentația dă viață unui API. Acesta explică componentele în detaliu într-un limbaj simplu care își vinde valoarea și utilizarea utilizatorilor. Utilizatorii vor consuma cu plăcere API-ul dvs. dacă au o experiență excelentă de dezvoltator.

O documentare bună ajută, de asemenea, la simplificarea întreținerii și scalarea API-ului. Echipele care lucrează cu API-ul pot folosi documentația pentru a-l gestiona.