(+39) 335 707 8284 [email protected]

Guide per interfacce software API

da | API, Metodo

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.


[1] Smartbear State of API 2019

Sperimenta l’Intelligenza Artificiale: Guida Pratica per Implementare un Chatbot Aziendale di Successo
Introduzione L'adozione di un chatbot aziendale in grado di fornire un accesso rapido e multilingue alla documentazione tecnica attraverso un'interfaccia conversazionale rappresenta una strategia innovativa. Questo approccio permette di ottimizzare l'efficienza...
Contenuti Modulari nella Comunicazione Aziendale

Il contenuto modulare è una strategia innovativa per la gestione e la creazione di contenuti. Consiste nel suddividere contenuti complessi in moduli riutilizzabili, che possono essere combinati per creare esperienze efficaci e coinvolgenti per i clienti. Questi moduli, simili a blocchi di costruzione, offrono efficienza, flessibilità, personalizzazione e dove necessario anche ottimizzazione SEO.

Assistente Virtuale Multilingua
Assistente Virtuale Multilingua: l'Innovazione per la Tua Azienda Scopri come semplificare l'accesso alle informazioni e migliorare il supporto clienti con il nostro assistente virtuale multilingua. Perché scegliere il nostro assistente virtuale? Accede...
Contenuti tecnici di qualità nella strategia di crescita aziendale

Un recente rapporto analizza dettagliatamente quasi 100 milioni di sessioni utente in 136 paesi, fornendo un quadro completo sul comportamento degli utenti riguardo ai contenuti tecnici. I risultati evidenziano l’importanza cruciale di offrire contenuti di alta qualità e ben strutturati per catturare l’interesse, supportare clienti e collaboratori, e favorire un utilizzo efficiente e automatizzato, con conseguenti significativi risparmi operativi.

Chatbot di accesso alla documentazione aziendale
Non vi piacerebbe avere un assistente virtuale in grado di individuare istantaneamente un dato di documentazione ponendo una semplice domanda, anche a voce? Ad esempio, per risolvere problemi urgenti o trovare informazioni su prodotti o servizi sparsi in più...
Guide di sicurezza informatica

Oggi è indispensabile una strategia per la sicurezza informatica e una adeguata documentazione. In questo quadro, può essere utile una competenza professionale che aiuti a redigere i nuovi documenti a partire da solidi e comprovati modelli e sappia operare con strumenti adeguati a tenere sotto controllo tutti i delicati contenuti tecnici.

Scrivere una guida di stile

Le guide di stile danno la possibilità di presentare un marchio in modo coerente. Fanno risparmiare tempo fornendo immediate rispose a dubbi e domande ripetitive e sono un necessario riferimento per la formazione di nuovi addetti.

Online help per applicazioni software

Online help, o “guida in linea” è il manuale d’uso immediatamente disponibile per assistere l’utente. L’applicazione software appare così seria e credibile, creando fiducia, dando piena autonomia all’utente e riducendo le chiamate di supporto.

Documentazione strutturata con CCMS

Esistono moderni strumenti per lo sviluppo della documentazione che garantiscono un approccio ottimizzato e strutturato con benefici di qualità e riduzione dei costi. Quali sono? Leggi qui.

Scrivere per comunicare valore

Come scrivere bene per ridurre le richieste di supporto, i reclami, i rischi di danni, i malfunzionamenti? Per avere beneficio di immagine e abbassare i costi di formazione e di assistenza?

Manuale d’uso e manutenzione

Cosa va scritto in un buon manuale d’uso e manutenzione? Come va impostato per coprire in modo adeguato i suoi scopi? Sapevi che esiste uno standard internazionale cui fare utile riferimento?

ChatBot e intelligenza artificiale: scrivere oggi per gli utilizzi di domani

Scrivere oggi con in mente i nuovi strumenti di intelligenza artificiale è opportuno e lungimirante, oltre che immediatamente migliorativo della qualità dei manuali classici.

Scopri i nostri servizi

Ti possiamo offrire consulenza, formazione, digitalizzazione…

Hai bisogno di maggiori informazioni?

Descrivi brevemente le tue esigenze, ti risponderemo a breve con la soluzione o il servizio più adatto.

Share This
Avvia chat
Ciao 👋
Come possiamo aiutarti?