Di cosa parliamo quando parliamo di documentazione API?
Com’è noto, l’API (Application Programming Interface) è un set di chiamate software che permettono a un programma di interagire con altri programmi, con database o altre risorse locali o in rete. Invece di scrivere del software per una particolare funzione, è pratico utilizzare un servizio esterno e comandarlo tramite le chiamate API.
Moltissime aziende e organizzazioni sviluppano oggi API pubbliche o private per i loro prodotti perché queste interfacce sono una soluzione pratica e sicura per comunicare e rendere i prodotti fruibili da applicazioni software.
Esistono diversi tipi di API. I più diffusi sono SOAP e REST:
- SOAP (Simple Object Access Protocol): standard di protocollo rigido e sicuro basato su strutture XML, con criteri di sicurezza intrinsechi.
- REST (Representational State Transfer): standard aperto, flessibile e scalabile basato sul protocollo HTTP. Richiede un’attenta implementazione con HTTPS per garantire sicurezza.
Documentazione API
Che cos’è in pratica la documentazione API? Si tratta di una guida scritta che illustra le funzioni dell’API, le modalità di comunicazione e soprattutto i casi d’uso, con esempi esplicativi.
Tale documentazione è molto importante. Una dettagliata indagine di mercato [1] indica tra i punti principali come investire maggiormente nella documentazione delle API permette ai fornitori di offrire la migliore esperienza ai clienti. Infatti, oltre la metà dei fornitori di API indica la qualità della documentazione come il fattore più importante per sviluppare API di qualità ed emergere nella competizione di mercato. Farsi capire e promuoversi con efficacia è come al solito essenziale!
D’altra parte, gli utenti hanno indicato la documentazione accurata e dettagliata come uno dei fattori più importanti nel valutare l’adozione di una API, dietro soltanto alla facilità d’uso (un fattore collegato, che tratteremo più sotto parlando degli esempi) e alle prestazioni.
Le API sono realizzate da sviluppatori software, che spesso creano anche la relativa documentazione. Il tipico risultato è un punto di vista molto tecnico, il che può rendere il documento difficile seguire e utilizzare, specie in caso di sviluppatori non ancora esperti. Un secondo problema è il tempo sottratto allo sviluppatore per la documentazione, anche in considerazione del fatto che scrivere un documento non è in genere un’attività gradita ai tecnici.
Una buona alternativa è quindi quella di assegnare il compito della documentazione API a un redattore tecnico (technical writer) che possa combinare esperienza di scrittura di contenuti e conoscenze tecniche per produrre una documentazione completa, corretta e anche informativa e ben comprensibile.
Il redattore deve imparare a conoscere l’API dagli sviluppatori e quindi prepara la documentazione con il supporto e la verifica degli sviluppatori stessi. Un redattore tecnico all’altezza può anche operare con gli strumenti di sviluppo, ad esempio Swagger, Postman, Dapperbox, per contribuire per la parte testuale e ben integrare le funzioni automatiche e interattive con la documentazione statica.Destinatari
Come per qualsiasi pianificazione di contenuti, il primo passo per scrivere la documentazione dell’API è comprendere chi sono i tipi di utente destinatario, il valore che il contenuto fornisce e come effettivamente lo viene utilizzato.
Tipicamente, esistono due gruppi di utenti da considerare: gli sviluppatori che useranno l’API, e quindi cercheranno tutorial ed esempi di codice, e i manager che valuteranno l’API, i suoi prezzi, i limiti e la sicurezza in modo da verificare come si allinea con esigenze e obiettivi aziendali.
Panoramica
La documentazione deve fornire una panoramica generale dell’API, prestando attenzione agli utenti destinatari, alle loro necessità. In pratica:
- Spiegare il perché di questa API, cosa può fare, quali problemi può risolvere
- In termini generali, la varietà di funzioni ed endpoint che offre
- Come si differenzia da altre soluzioni e dalla concorrenza
Autenticazione
L’autenticazione è il primo passo del percorso utente ed è essenziale per mantenere i dati sicuro. Tipicamente, un’API deve quindi avere uno o più metodi di autenticazione, ad esempio una chiave API o il protocollo aperto OAuth 2.0. La documentazione deve spiegare ogni metodo per accedere all’API e per utilizzarla.
Limiti e condizioni di utilizzo
I limiti di prestazione devo essere specificati per prevenire un abuso accidentale o intenzionale di un’API. Un limite importante (rate limiting) è il numero massimo di chiamate gestibili in un determinato periodo di tempo. Questo e altri possibili limiti devono essere chiaramente indicati nella documentazione, in modo che gli utenti sappiano come utilizzare correttamente l’API e di cosa esattamente è capace.
Queste informazioni si trovano spesso nelle condizioni d’uso, che definiscono l’accordo legale tra il fornitore di servizi e la persona o l’organizzazione utilizzatore, che deve accettare di rispettare le condizioni indicate. Nella documentazione dell’API, le condizioni d’uso devono definire chiaramente come l’utente può utilizzare l’API.
Storico degli aggiornamenti
È essenziale che gli utenti siano informati delle modifiche apportate alle API che utilizzano. Questo permette loro di mantenere le applicazioni sempre compatibili e sfruttare a pieno il potenziale della piattaforma API. La documentazione deve comprendere la lista di tutte le modifiche apportate in corrispondenza delle versioni di rilascio del software.
Esempi, Esempi, Esempi!
Gli esempi di codice sono fondamentali per rendere agevole l’utilizzo dell’API e presentare efficacemente tutte le sue potenzialità. La già citata ricerca di mercato [1] indica la facilità d’uso come la qualità più apprezzata di un’API. La documentazione deve quindi comprendere tali esempi in adeguata varietà e quantità.
Codici e messaggi di errore
La documentazione deve indicare chiaramente tutti i codici e messaggi di errore che gli utenti possono aspettarsi quando effettuano una chiamata API. Ogni tipo di risposta deve essere accompagnata da una breve descrizione, in modo che gli utenti possano capire se la chiamata è andata a buon fine oppure no e perché, per poter risolvere rapidamente eventuali errori (senza rivolgersi e intasare il supporto tecnico!). Una buona documentazione di errori ed eccezioni è utilissima anche internamente, nel lavoro di sviluppatori e i tester.
Conclusioni
La documentazione di API è quindi importante e deve essere chiara ed efficace. Va infine ricordato che anche per questo tipo di documenti valgono tutte le considerazioni sul modo migliore di comunicare contenuti tecnici, come abbiamo discusso in altri articoli, uno per tutti: Scrivere per comunicare Valore.
Se ti può interessare questo tema, contattaci per un approfondimento libero da impegni.
