API (Application Programming Interface) è un software che consente lo scambio di dati tra applicazioni e dispositivi, oltre a facilitare la connettività tra dispositivi e programmi. L'API può anche essere definita come un'interfaccia che consente a un'applicazione aziendale di comunicare con i sistemi di backend, promuove la comunicazione senza interruzioni tra più applicazioni ed espone solo una quantità limitata delle funzioni interne di un programma. Vedi anche: Che cos'è l'API. Differenza tra REST e GraphQL
Principalmente le API vengono utilizzate per stabilire un collegamento tra applicazioni e dispositivi. La creazione di un'API REST adeguata può aiutare a creare un'integrazione funzionale tra i componenti richiesti. Tuttavia, un'implementazione errata potrebbe compromettere l'intero progetto.
Per implementare una buona architettura di progettazione dell'API REST, è necessario seguire alcune regole di base, che sono le seguenti:
- Conoscere le applicazioni e i casi d'uso associati prima dell'implementazione prevista.
- È molto importante conoscere i vincoli HTTP.
- Segui l'architettura e il framework vincolante utilizzati per l'ingegneria.
- Garantire la corretta gestione delle modifiche degli endpoint già esposti.
La progettazione di un'API e la gamma di servizi rappresentati sono i driver primari della progettazione. Tuttavia, gli sviluppatori e gli architetti del software spesso tendono a ignorare l'obiettivo generale coinvolto nella creazione di API.
Il design delle API non riguarda solo l'enfasi su un software strutturato, ma si concentra anche sull'essere user friendly. Una buona API può supportare un insieme ben definito di casi d'uso o scenari. Di seguito sono menzionati i seguenti fattori chiave che si dovrebbero considerare quando si cerca una buona API.
- Superare le sfide per mantenere un'alta qualità dell'API
- Facilità d'uso: gli endpoint API dovrebbero essere abbastanza facili da eseguire le attività di base.
- Miglioramento dell'efficienza: il modello di progettazione dovrebbe essere facile da apprendere in modo che lo sviluppatore possa eseguire rapidamente il lavoro richiesto dopo aver appreso il modello di progettazione.
- Buona consistenza: una buona API consentirà agli sviluppatori di ristabilire facilmente la competenza anche se tornano dopo un periodo di interruzione.
- Controllo di qualità: aiuta a tenere traccia della frequenza degli errori commessi dagli sviluppatori, della gravità di questi errori e della velocità con cui possono essere recuperati.
- Aumento della soddisfazione: l'API offre una piacevole esperienza utente del design dell'applicazione.
La pianificazione e il test sono i due componenti importanti dello sviluppo di un'API. Senza di essi, un ciclo di sviluppo potrebbe diventare ampio con un tasso di difettosità più elevato. Un'API di buona qualità è quindi importante sia per i consumatori che per i fornitori di API. Nel caso dei consumatori, un'API difettosa potrebbe significare un ciclo di sviluppo più lungo e un tasso di errore più elevato. In alcuni casi potrebbero anche sorgere problemi legati al lavoro di squadra. Ad esempio: dipendenza dall'unica persona che ha imparato l'arte di chiamare correttamente l'API.
Fortunatamente, sono emersi molti strumenti e approcci di progettazione che producono risultati migliori e più coerenti nello sviluppo delle API. Questi approcci di progettazione si concentrano sull'utilizzo delle migliori pratiche presso le organizzazioni leader, considerando l'usabilità e implementando strumenti appropriati.
-Comprensione approfondita del protocollo HTTP e della sua capacità di gestire i post e le richieste. Questo è importante perché REST è costruito sulla base di HTTP.
-Buona conoscenza su come stabilire un collegamento tra le risorse e il codice.
-Determinare come una singola risorsa può essere rappresentata rispetto ad un gruppo di risorse. Sebbene non siano disponibili standard formali, gli sviluppatori devono comunque fare riferimento alle migliori pratiche durante questa operazione.
Attualmente sono disponibili molti framework API aziendali. L'utilizzo di uno di questi può aumentare la qualità complessiva dell'API, facilitandone la comprensione e l'utilizzo, migliorando al contempo la produttività complessiva.
- Le API possono essere visualizzate come un insieme di endpoint guidati da verbi e nomi. Una frase contenente un verbo rappresenta un'azione richiesta (come get, put, delete), mentre i nomi denotano argomenti appropriati all'azione. È buona norma generare sempre uno stato o una variabile di risultato che comunichi le condizioni di errore o l'esecuzione corretta.
- La sintassi dell'API è importante perché con la capacità dell'API di trasmettere i propri servizi e parametri, gli errori degli sviluppatori vengono chiaramente ridotti.
- Le condizioni di errore dovrebbero essere sufficientemente complete da comunicare gli ostacoli all'utente finale.
Quando cerco sul web delle API da utilizzare in un mio progetto la prima cosa su cui faccio attenzione è se le API che voglio utilizzare hanno una documentazione di ottima qualità; se quel progetto non offre una documentazione chiara e con esempi di utilizzo scarto subito quel progetto di API. Quando si progetta delle API occorre assolutamente fornire agli utilizzatori la documentazione:
- Descrizione del servizio offerto dalla API
- Url della API
- Elenco degli eventuali parametri o body payload accettati in input, riportando dettagliatamente la struttura che devono avere e il significato semantico del parametro
- Struttura della risposta della API sia in caso di successo che di errore
- Significato dei diversi stati HTTP della risposta della API. Ad esempio se un API che utilizzo mi risponde con l’errore 404 NOT FOUND, mi aspetto che nella documentazione sia riportato in quali occasioni viene sollevato questo errore.
Esistono diversi Tool riconosciuti come standard dalla community per la produzione di documentazione di API. Riporto quelli che a mio avviso sono i migliori:
- Swagger
- Github Wikis
- Slate
Io personalmente uso Swagger, in quanto recentemente ha lanciato la Specifica OpenAPI (conosciuta originariamente come la Specifica Swagger), una specifica per file di interfaccia leggibili dalle macchine per descrivere, produrre, consumare e visualizzare servizi web RESTful. Con i tool di Swagger hai a disposizione una serie di tool per generare:
- il codice dei tuoi model, e non solo, a partire dalla specifica delle API
- la documentazione
- i test case
Swagger è adatto anche all’uso interno in un team di sviluppo, per avere delle specifiche delle API utili sia per chi sviluppa sia al team frontend che le utilizza.
Nel mondo delle applicazioni a componenti, le API RESTful vengono gradualmente considerate superiori nel mondo dell'integrazione. Mentre le aziende approfondiscono la ricerca di nuove tecnologie che le aiutino a riguadagnare velocità, mantenere l'agilità e sfruttare i dati, le interfacce applicative come le API sono il big bang in termini di astrazione. In effetti, tutte le principali applicazioni software oggi hanno iniziato a esporre le API in modo che i loro clienti possano trarre ulteriori vantaggi dai loro prodotti.
Programmatore informatico italiano, mi occupo di sviluppo sia Front-end che Back-end presso una grande azienda. La programmazione è stata la mia passione, insieme allo sport e al teatro che pratico tutt'ora. Ho deciso di aprire questo blog per dare consigli e condividerli con chi, come me, porta con sé questa passione. [..]
