Tempo di lettura: 9 minuti
Le API fanno girare il mondo. Gli sviluppatori usano le API quasi ogni giorno – secondo alcune stime, passano più di 10 ore alla settimana a lavorare con le API. Questo comprende non solo il loro utilizzo, ma anche la ricerca, la ricerca su Google del supporto, lo studio delle recensioni e, naturalmente, il rovistare nella documentazione. Quanto chiara, facile, utile e supportata sia la tua API determina l’intera esperienza dello sviluppatore (DX) – una risposta emotiva che i dev hanno verso il prodotto. Nell’economia delle API, una grande esperienza dello sviluppatore è fondamentale. Le API che aiutano gli sviluppatori ad avere successo e sono una gioia da usare otterranno tonnellate di utenti e supereranno la concorrenza. E inizia nel momento esatto in cui aprono la documentazione per la prima volta.
Guarda questo video per un’introduzione alla tecnologia API
Oggi parleremo di come favorire un’esperienza positiva per gli sviluppatori nella documentazione API. Ma prima, dobbiamo capire cosa rende cattivi i documenti API.
Cosa odiano gli sviluppatori nella documentazione API
La comunità di sviluppatori è appassionata. È specificamente appassionata delle cose che non gli piacciono. Se non amano un’API, la maggior parte delle volte è a causa di una documentazione scadente, anche se il prodotto è effettivamente ottimo. Ecco alcuni problemi comuni che gli sviluppatori hanno con i documenti delle API.
Non è scritto usando un linguaggio umano semplice. Questo è un problema comune per i docs auto-generati o per i docs trascurati dai creatori. Anche se molti strumenti di generazione della documentazione fanno un ottimo lavoro nel commentare il codice, non possono sostituire le spiegazioni reali in inglese scritte da uno sviluppatore o da uno scrittore tecnico.
Ha pochi esempi di codice. Questa è un’altra estremità dello spettro in cui le spiegazioni sono abbondanti, ma ci sono esempi minimi del codice reale.
È disponibile solo per gli utenti registrati. Questa manovra non molto intelligente non fa nulla per il vostro marketing. Frustra solo le persone che vogliono sapere cosa fa la vostra API prima di decidere se la vogliono (come farebbe qualsiasi persona sana di mente).
È troppo lungo/non si trova/è impreciso/non viene aggiornato da anni, ecc. Creare una buona documentazione è importante quasi quanto costruire una buona API. Perché i documenti scritti male o quelli che non possono essere trovati semplicemente cercando su Google “Product API” stanno fallendo l’intero sforzo di sviluppo. Se siete interessati, abbiamo già delineato le specifiche della documentazione tecnica in generale. Ma i documenti API meritano un articolo dedicato. Quindi come si fa a scrivere ottimi documenti API?
Adotta lo sviluppo guidato dalle specifiche
Lo sviluppo guidato dalle specifiche (SDD) è simile allo sviluppo guidato dai test in cui si scrivono casi di test per ogni caratteristica e poi si scrive il codice che dovrebbe superarli. In SDD, si crea la documentazione o almeno alcune parti di essa in parallelo con la costruzione di un’API, spesso seguendo un certo formato di descrizione dell’API chiamato specifica.
Una specifica API è come un modello dei vostri futuri documenti, il linguaggio unificato che descrive il design della vostra API, spiega come funziona e cosa aspettarsi da essa. Ci sono alcune specifiche, come RAML (RESTful API Modeling Language), OpenAPI (ex Swagger), e API Blueprint, ma c’è una tendenza in corso per combinare tutte le specifiche sotto il cofano di OpenAPI.
Queste specifiche hanno strumenti di documentazione precostituiti che permettono di scrivere e gestire i vostri documenti. Per esempio, API Console genera automaticamente i documenti dai formati RAML e OpenAPI e ti aiuta a eseguirli sulla tua applicazione web esistente o come un’applicazione indipendente.
API Console ti permette di costruire un portale web per i tuoi documenti API dalle specifiche RAML e OpenAPI
Fonte: Pawel Psztyc
Alternativa alle tradizionali soluzioni API doc come WordPress o Drupal CMS, i prodotti API spec sono open source, creati dalla comunità di sviluppatori per la comunità di sviluppatori, hanno parser in diversi linguaggi di programmazione, e supporto costante ai creatori.
Scrivi per l’entry level
C’è una ragione per cui la documentazione tecnica di solito non è scritta dagli sviluppatori stessi – è il lavoro dei technical writer, esperti nel tradurre aspetti tecnici in un formato leggibile. Ma anche gli scrittori tecnici tendono a far trapelare un po’ di gergo nel testo.
Un’API come qualsiasi prodotto software è creata per un pubblico specifico. Ma il pubblico della documentazione è vasto. Ci sono tre gruppi principali di utenti della documentazione:
- sviluppatori che interagiranno intimamente con la documentazione
- decisori come CTO e architetti di soluzioni che vogliono determinare se la vostra API sarà una buona soluzione rapidamente
- osservatori come giornalisti, scrittori tecnici e persino concorrenti che non useranno mai necessariamente la vostra API.
E anche all’interno di ognuno di questi gruppi, ci sono persone con diverse abilità, ruoli e bisogni, e tutti loro dovrebbero avere un’esperienza positiva con i documenti. Come si fa a indirizzarli tutti? Prendendo di mira gli utenti meno esperti. Quindi, come si scrivono i documenti per un nuovo arrivato?
Iniziare con le opportunità piuttosto che con i tecnicismi. Accogliete gli utenti con una storia avvincente che racconti come la vostra API può arricchire il loro prodotto o rendere la vita degli sviluppatori dieci volte più facile.
I documenti API di Amazon Alexa iniziano con lo spiegare cosa fa Alexa e quali benefici può portare al cliente
Mostra da dove iniziare. I documenti API sono noti per essere troppo travolgenti e per presumere che gli utenti abbiano una vasta esperienza con le API. La sezione per iniziare è obbligatoria, e dovrebbe essere scritta con pazienza per un potenziale utente.
Facebook fornisce un chiaro riferimento per i principianti e segue il processo per iniziare passo dopo passo
Crea istruzioni per i casi d’uso più comuni. Probabilmente sapete già per quali funzioni la gente usa la vostra API. Create sezioni separate che si rivolgano a loro e includete messaggi di esempio.
Utilizzate un tono colloquiale. La comunità degli sviluppatori è rilassata e informale, quindi non apprezzeranno l’arido linguaggio aziendale anche se suona più “professionale”. I buoni documenti parlano sempre agli esseri umani.
Educate sugli strumenti esterni. Se la vostra API richiede l’uso e la comprensione di prodotti e concetti di terze parti come OAuth o npm, includete link a documenti o guide all’installazione.
Fate in modo che sia facile da imparare. I documenti API non sono istruzioni di montaggio IKEA, ma sono la fonte di apprendimento. Arricchisci la tua documentazione con FAQ, tutorial, blog e persino video quando possibile.
Incorpora le sezioni must-have
Nel 2019, SmartBear, lo sviluppatore di Swagger, ha intervistato gli sviluppatori e gli utenti API. Hanno trovato quali caratteristiche di docs sono considerate le più importanti nella comunità, dandoci un elenco delle sezioni di documentazione must-have che i dev vogliono coprire. Ne esamineremo alcune.
SmartBear ha intervistato 3.000 professionisti API
Esempi. Gli esempi sono di solito presentati come pezzi di codice, che sono abbastanza utili ma possono essere resi ancora più pratici. Per esempio, includendo una trascrizione dei campi come si fa nei documenti di Medium o anche creando una mock API per gli sviluppatori da testare e usare facendo chiamate reali. Le mock API possono essere facilmente condivise tramite un URL o su GitHub, e se fatte con un certo livello di dettaglio, anche utilizzate nel prodotto finale.
Status ed errori. Ci sono codici di stato standard e quelli specifici delle vostre API. È una buona idea includere tutti gli errori che possono essere innescati dalla vostra API. Gli errori sono spesso messi in una pagina dedicata della documentazione, ma ha senso duplicare alcuni di essi direttamente sotto l’endpoint dove emergono maggiormente.
Autenticazione. La maggior parte dei documenti API inizia con l’autenticazione e l’autorizzazione. Dovrebbe coprire le informazioni su come ottenere una chiave API e come autenticare le richieste, compresi i possibili errori, i tempi di scadenza dei token, e una spiegazione sulla sensibilità dell’autenticazione (fondamentalmente ricordando che le chiavi non possono essere condivise, e dove possono essere utilizzate).
Richieste HTTP. Fornire richieste web in HTTP è il minimo indispensabile per la documentazione. Di solito si presume che gli sviluppatori sappiano come inviare richieste HTTP nella loro lingua preferita, ma a volte i creatori di API includono richieste in varie lingue. Questo può essere fatto automaticamente tramite strumenti di specifiche API e strumenti di gestione API come Postman.
Usa il layout standard del settore
Se stai usando un generatore di documentazione, il layout è già deciso per te. La maggior parte dei documenti API hanno lo stesso aspetto. Se ne avete usati alcuni, sapete come avvicinarvi ai nuovi documenti. Tuttavia, organizzare grandi volumi di dati, renderli reperibili e facili da navigare è un compito complesso. Ecco alcune caratteristiche dei layout più funzionali.
Disposizione dinamica. Si può riconoscere un’API obsoleta dalla sua documentazione statica. Una pagina singola o anche un documento PDF non è sufficiente nel 2020. I documenti dinamici sono facili da sfogliare, aggiornare e mettere nei preferiti.
Contenuti appiccicosi. No, la barra di navigazione non distrae e non ruba spazio prezioso sullo schermo. Tieni sempre i contenuti in vista.
Disposizione a tre colonne. Non usato molto spesso, questo layout permette di avere un’altra colonna a destra per gli esempi di codice. Naturalmente, questo ha senso solo se hai una tonnellata di testo e vuoi evidenziare il codice in modo che gli utenti non debbano scorrere avanti e indietro o passare da una scheda all’altra.
I documenti API di HubSpot usano un layout a tre colonne
Usa colori a contrasto per la sintassi. Gli sviluppatori passano molto tempo a guardare i tuoi esempi di codice, quindi rendili leggibili e separa i diversi componenti per colore.
Questo esempio dai documenti Graph API di Facebook mostra anche come puoi usare diverse schede per scegliere tra SDK
Salva lo stato di scorrimento. Questo è un piccolo dettaglio che ogni sviluppatore apprezzerà. Puoi anche usare link di ancoraggio per specificare diverse sezioni della pagina nel caso in cui copino l’URL.
Incoraggia il feedback. I vostri documenti sono il vostro principale strumento di marketing – se le persone li amano, useranno la vostra API rispetto a quella dei concorrenti e guideranno la comunità intorno ad essa. Il solito messaggio “Questa pagina ti è stata utile?” ti farà sapere quanto bene stai rispondendo alle domande degli sviluppatori e il modulo di feedback sarà usato spesso fino a quando lo farai.
Non abbandonare i tuoi documenti
I documenti obsoleti sono la più grande lamentela degli utenti API. Questo è anche uno degli errori più comuni. Gli sviluppatori spesso scrivono sugli aggiornamenti diversi giorni dopo il loro lancio, a volte limitandosi a poche frasi. Questo accade perché non c’è un processo stabilito per gli aggiornamenti dei documenti e non è responsabilità di nessuno. Ecco come assicurare aggiornamenti regolari e utili dei documenti.
Prepara i documenti prima degli aggiornamenti. Fatene un passo aggiuntivo nel vostro piano di lancio, non lanciateli prima di avere paragrafi ben scritti, dettagliati e modificati per introdurre i vostri aggiornamenti.
Rimuovete regolarmente i dati deprecati. I documenti devono essere rivisti spesso, almeno una volta ogni pochi mesi. Le funzioni di feedback degli utenti vi permetteranno di cogliere prima le incongruenze e ci dovrebbe essere sempre un membro del team responsabile della revisione e della reazione agli aggiornamenti.
Utilizzare l’analitica per migliorare i documenti. Le analisi standard delle API vi diranno quali endpoint sono usati più spesso, così potrete concentrarvi su certe parti della documentazione e fornire informazioni più utili o creare tutorial dedicati. Monitorate i casi d’uso per cui le vostre API sono usate, perché questo vi permetterà di ampliare la proposta di valore e di aggiornare i documenti con più possibilità.
Grandi esempi di documentazione API
Ci sono tonnellate di buoni documenti da esplorare e da cui imparare. Oltre agli esempi che abbiamo condiviso nel corso dell’articolo, qui ce ne sono alcuni altri che vi possono piacere e di cui potete prendere nota.
Documentazione API di Medium
I documenti API di Medium non rispettano necessariamente tutte le regole che abbiamo elencato oggi, ma sono ottimi per la funzionalità limitata che questa API supporta – pubblicare e cercare pubblicazioni su Medium. Sono condivisi su GitHub, hanno contenuti veramente brevi ma chiari con tonnellate di esempi, ognuno dei quali termina con una trascrizione di tutti i parametri menzionati nel codice, compresi i possibili errori. È straordinariamente semplice, ma affidabile – tutti i suggerimenti possono essere fatti direttamente su GitHub e i documenti sono regolarmente aggiornati.
Documentazione API di Mailchimp
Mailchimp si rende conto che la maggior parte del suo pubblico sono professionisti del marketing e usa un linguaggio che permette anche ai non tecnici di capire come lavorare con le sue API. A colpo d’occhio, ogni sezione segue la stessa struttura:
- cosa fa un endpoint e cosa la guida permette agli utenti di fare
- di cosa avrete bisogno – qualsiasi accesso o account che un utente deve ottenere prima
- che cos’è ogni funzione con una descrizione testuale, un esempio di codice in diverse lingue, e talvolta screenshot dell’interfaccia.
C’è anche un pulsante di copia per ogni pezzo di codice – un dettaglio che i non tecnici apprezzeranno sicuramente.
Documentazione API di Twilio
Twilio ha dei docs API famosi. Anche se i documenti sono solo la punta dell’iceberg di tutto l’aiuto che Twilio condivide – ci sono SDK in diverse lingue e applicazioni di esempio per iOS, Android e web. Prima di tutto, seguono la logica a tre colonne con il codice direttamente a destra della guida. Le azioni più semplici sono spiegate con dettaglio e tonnellate di link per informazioni aggiuntive e screenshot. Il feedback è anche incoraggiato tramite un pulsante “Rate this page” e link al team di supporto e al tag su StackOverflow.
Documentazione API di Spotify
Anche se i documenti API web di Spotify sono molto tipici, hanno un sacco di informazioni aggiuntive nella sua piattaforma Spotify for Developers. Ci sono demo per le funzioni di base, applicazioni finte, esempi dal vivo costruiti usando le API e i widget di Spotify, wrapper per diversi linguaggi di programmazione e, naturalmente, la console. La console è fondamentalmente una documentazione interattiva dove potete inserire i vostri dati (o campioni) ed esplorare gli endpoint dal vivo. Prodotti potenti insieme a una forte base di conoscenza rendono Spotify un partner affidabile con cui gli sviluppatori amano lavorare.
Tratta i documenti con cura
La documentazione è l’unico punto di contatto che avrai con la maggior parte del tuo pubblico, quindi devi imparare a comunicare chiaramente attraverso di essa. Il miglior suggerimento qui è quello di renderlo il lavoro di qualcuno. Spesso si tratta di uno scrittore tecnico che sa come parlare a un pubblico di diverse competenze, che può tradurre le parole degli sviluppatori in punti praticabili, che controlla la manutenzione e l’aggiornamento tempestivo della documentazione. Ma gestire una grande documentazione è possibile anche senza un esperto nel vostro staff. Gli strumenti di gestione delle API come Swagger UI, Spotlight, Apiary, e gli strumenti di specificazione dei documenti hanno un’ampia funzionalità per aiutarvi a creare documenti che gli sviluppatori ameranno.