Da una richiesta a una documentazione che qualcuno legge
La documentazione delle API marcisce perché viene scritta separatamente dalle richieste. Generarla dalla collection è l’unica versione che resta vera.
Quasi tutta la documentazione delle API mente entro il terzo mese. Non perché qualcuno abbia mentito, ma perché la documentazione vive in un posto e le richieste in un altro, e solo una delle due viene aggiornata quando cambia un campo.
Lodos chiude quel divario generando la documentazione dalla collection contro cui stai già testando. È tutto il senso di avere i due moduli affiancati, e cambia il modo in cui dovresti organizzare la collection fin dal primo giorno.
Organizza la collection per la documentazione, non per te
API Post/Get supporta tutti i metodi HTTP, collection con cartelle, gestione di header e autorizzazione e un visualizzatore di risposte con evidenziazione della sintassi. La struttura di cartelle che scegli diventerà la struttura della tua documentazione, quindi vale cinque minuti di riflessione.
Raggruppa per risorsa, non per attività. Una cartella users con elenco, creazione, aggiornamento ed eliminazione si legge come documentazione. Una cartella flusso di registrazione con tre richieste da tre risorse diverse si legge come il tuo blocco appunti personale, perché è esattamente quello.
Dai alle richieste il vocabolario dell’API stessa. GET /users/:id è meglio di prendi un utente, perché chi legge la documentazione sta cercando di far combaciare ciò che vede con l’endpoint che sta chiamando.
Sono le variabili d’ambiente a farla sopravvivere
È la differenza tra una collection che dura un anno e una che smette di funzionare la prima volta che lo staging si sposta.
Metti ogni host, ogni token e ogni identificatore che cambia in una variabile d’ambiente. {{base_url}}/users/{{test_user_id}} è una richiesta che funziona su locale, staging e produzione cambiando un menu a tendina. Una richiesta con https://staging-2.example.com incastrato nell’URL è una richiesta che si rompe in silenzio in tre settimane e viene riscritta da chi ne avrà bisogno dopo.
Gli script pre-richiesta risolvono il caso che blocca di più: un token di autorizzazione che scade. Recuperalo in un passaggio preliminare e salvalo in una variabile d’ambiente, e smetterai di incollare un bearer nuovo in undici richieste ogni mattina.
Le credenziali, onestamente
Una collection appartiene allo spazio di lavoro: chiunque vi abbia accesso la vede, valori dei tuoi ambienti compresi.
Trattalo come il vincolo di progettazione che è. Credenziali di sviluppo e staging nella collection vanno bene e sono davvero utili: chi eredita il tuo lavoro non dovrebbe doverle cercare. Quelle di produzione no. Se un valore sarebbe un problema in uno screenshot, non deve stare in un ambiente condiviso.
L’impostazione pratica: un ambiente per stadio, con la produzione deliberatamente incompleta, così che lanciare contro di essa richieda un atto consapevole e non una selezione sbagliata in un menu.
Trasformarla in documentazione
API Documentation genera dalla collection e ci mette sopra un editor di testo ricco, gestione delle versioni, generazione di snippet di codice, esportazione PDF e link condivisibili.
La parte generata copre cosa sia l’endpoint e cosa accetti. Ciò che non può sapere è perché qualcuno dovrebbe chiamarlo — ed è proprio la parte che serve a chi legge. Lo schema che funziona:
- Genera dalla collection. Non scrivere a mano l’elenco degli endpoint; deriverà.
- Aggiungi un breve paragrafo per risorsa che spieghi a cosa serve e quando la useresti.
- Documenta gli errori. Non il 200 — il 409 che significa che l’e-mail è già presa, e cosa dovrebbe farne il client.
- Pubblica un link invece di esportare un PDF, a meno che qualcuno chieda esplicitamente un file. Un link resta attuale; un PDF è la fotografia di un momento.
La gestione delle versioni conta quando hai consumatori esterni. Congela una versione nel punto in cui qualcuno inizia a costruirci sopra, così che dopo una modifica esista ancora un documento che descrive su cosa aveva costruito.
Le 130 piccole cose
Vale la pena saperlo perché risparmia una scheda del browser: il modulo Tools ha oltre 130 utility — formattatori JSON e XML, encoder, convertitori, generatori di hash. Girano interamente nel tuo browser, non viene caricato nulla e non costano token.
Quest’ultimo dettaglio pesa più di quanto sembri. Incollare un payload in un formattatore JSON online qualsiasi significa incollare i tuoi dati sul server di qualcun altro. Se dentro ci sono i dati di un cliente, è un piccolo incidente che nessuno noterà mai. Lo strumento locale toglie la tentazione.
Domande frequenti
Posso importare una collection esistente?
Le collection si costruiscono in API Post/Get con cartelle, header, autorizzazione e ambienti. Se arrivi da un altro strumento, ricostruisci le richieste che usi davvero invece di importare tutto: quasi tutte le collection si trascinano anni di endpoint morti che nessuno chiama più.
Chi può vedere le credenziali nei miei ambienti?
Chiunque abbia accesso allo spazio di lavoro. Tieni lì i valori di sviluppo e staging, lascia fuori la produzione. La prova è semplice: se un valore sarebbe un problema in uno screenshot, non appartiene a un ambiente condiviso.
La documentazione si aggiorna se cambio una richiesta?
La parte generata viene dalla collection, quindi rigenerare recepisce la modifica. Il testo scritto a mano resta com’è — ed è per questo che la parte scritta a mano dovrebbe spiegare perché un endpoint esiste invece di ripeterne i parametri.
Meglio esportare un PDF o condividere un link?
Un link, a meno che qualcuno abbia bisogno proprio di un file. Un link condiviso riflette la versione corrente; un PDF è la foto di un momento e inizia a essere sbagliato il giorno dopo averlo mandato.
