Voi scrie o documentație API clară pe care dezvoltatorii tăi o pot urma din prima zi

De ce majoritatea documentațiilor API eșuează

Ele descriu punctele finale și omit părțile care îi opresc de fapt pe oameni: cum să te autentifici, cum arată o cerere realistă, ce înseamnă eroarea și ce să faci în legătură cu ea. Cititorul deschide apoi un tichet de suport, care este costul pe care documentația există pentru a-l elimina.

Cum o scriu

Din sursă, nu din memorie. Citesc rutele, stratul de validare și gestionarii de erori, apoi apelez API-ul eu însumi cu credențiale reale. Fiecare exemplu din documentație este o cerere pe care am făcut-o și un răspuns pe care l-am primit — fără sarcini utile inventate, fără coduri de stare pe care punctul final nu le returnează niciodată.

Ce conține documentația

• Autentificare: obținerea unui token, reîmprospătarea acestuia și ce se întâmplă când expiră în timpul sesiunii.
• Fiecare punct final cu parametri, un exemplu complet de cerere și forma reală a răspunsului.
• O referință de erori care mapează fiecare cod de eroare la o cauză și o soluție, în loc să repete doar mesajul.
• O cale de inițiere care duce un nou dezvoltator de la zero la un apel reușit în mai puțin de zece minute.
• Limite de rată, paginare, webhook-uri și idempotency explicate acolo unde se aplică de fapt.

Format

Markdown în depozitul dvs., structurat pentru OpenAPI sau un site de documentație — oricare dintre ele veți menține de fapt. Exemple de cod în limbile despre care utilizatorii dvs. întreabă, verificate prin rularea lor. Colecție Postman sau similară inclusă dacă doriți una.

Ce am nevoie

Acces la depozit sau fișierul OpenAPI, o credențială funcțională pentru un mediu de testare și orice întrebări la care echipa dvs. de suport s-a săturat să răspundă. Aceste întrebări sunt schița.

Nu este inclus

Text de marketing. Acesta documentează ce face software-ul, cu precizie; pagina de destinație este o altă meserie.

Timp de execuție și comunicare

O primă schiță completă sosește de obicei într-o săptămână, iar dvs. o revizuiți în funcție de întrebările la care echipa dvs. de suport continuă să răspundă. Prefer să fiu corectat devreme de inginerul care cunoaște cazurile limită decât să livrez ceva lustruit și greșit. Fiecare exemplu din documentul final a fost executat împotriva API-ului dvs., deci nimic din el nu este aspirațional.