Scriverò una documentazione API chiara che i tuoi sviluppatori potranno seguire fin dal primo giorno

Perché la maggior parte delle documentazioni API fallisce

Descrivono gli endpoint e saltano le parti che in realtà bloccano le persone: come autenticarsi, come appare una richiesta realistica, cosa significa l'errore e cosa fare al riguardo. Il lettore apre quindi un ticket di supporto, che è il costo che la documentazione esiste per eliminare.

Come la scrivo

Dalla fonte, non dalla memoria. Leggo le rotte, il livello di validazione e i gestori degli errori, quindi chiamo l'API io stesso con credenziali reali. Ogni esempio nella documentazione è una richiesta che ho fatto e una risposta che ho ricevuto — nessun payload inventato, nessun codice di stato che l'endpoint non restituisce mai.

Cosa contiene la documentazione

• Autenticazione: ottenere un token, aggiornarlo e cosa succede quando scade a metà sessione.
• Ogni endpoint con parametri, un esempio di richiesta completo e la forma della risposta reale.
• Un riferimento agli errori che mappa ogni codice di errore a una causa e una soluzione, piuttosto che limitarsi a ripetere il messaggio.
• Un percorso introduttivo che porta un nuovo sviluppatore da zero a una chiamata riuscita in meno di dieci minuti.
• Limiti di velocità, paginazione, webhook e idempotenza spiegati dove effettivamente si applicano.

Formato

Markdown nel tuo repository, strutturato per OpenAPI o un sito di documentazione — quello che effettivamente manterrai. Esempi di codice nelle lingue richieste dai tuoi utenti, verificati eseguendoli. Collezione Postman o simile inclusa se ne desideri una.

Cosa mi serve

Accesso al repository o al file OpenAPI, una credenziale funzionante per un ambiente di test e qualsiasi domanda a cui il tuo team di supporto è stanco di rispondere. Queste domande sono la base.

Non incluso

Testi di marketing. Questo documenta ciò che il software fa, precisamente; la landing page è un'arte diversa.

Tempi di consegna e comunicazione

Una prima bozza completa di solito arriva entro una settimana, e tu la rivedi rispetto alle domande a cui il tuo team di supporto continua a rispondere. Preferisco essere corretto presto dall'ingegnere che conosce i casi limite piuttosto che consegnare qualcosa di rifinito e sbagliato. Ogni esempio nel documento finale è stato eseguito sulla tua API, quindi nulla in esso è aspirazionale.