Quali sono i componenti di un'API?

Le API sono insiemi di istruzioni basate su codice che consentono ai componenti software di comunicare e trasferire dati e sono gli elementi costitutivi di tutte le applicazioni moderne. Ma quali sono gli elementi costitutivi delle stesse API? In questo articolo, esamineremo i diversi componenti di un'API REST seguendo una richiesta dall'inizio alla fine.

Cliente dell'API

Le richieste API possono essere attivate in molti modi diversi. Ad esempio, un utente potrebbe avviare una richiesta API inserendo un termine di ricerca, facendo clic su un pulsante o scorrendo un elenco su un'applicazione Web o mobile. Le richieste API possono anche essere emesse in risposta a eventi esterni, come una notifica da un'altra applicazione o servizio. Indipendentemente da come viene attivata la richiesta API, un client API sarà responsabile dell'assemblaggio e dell'indirizzamento al server API.

È importante notare che la frase "client API" può significare cose diverse a seconda del contesto. Innanzitutto, può fare riferimento a uno strumento di sviluppo che astrae parte della complessità dell'invio manuale delle richieste API, il che semplifica l'esplorazione, il test e il debug delle API. Può anche fare riferimento a un servizio che utilizza librerie e SDK specifici della lingua per avviare richieste API nel contesto di un'applicazione più ampia. Entrambi i tipi di client API sono responsabili della gestione dei dati restituiti dall'API e della loro presentazione all'utente, ma quest'ultimo tipo di client può anche utilizzare i dati restituiti nel flusso logico dell'applicazione.

Richiesta API

Abbiamo accennato al fatto che un client API è responsabile dell'invio di richieste API in risposta ad azioni dell'utente o eventi esterni, ma cos'è esattamente una richiesta API? Una richiesta API avrà un aspetto e un comportamento diverso a seconda del tipo di API. Detto questo, una richiesta API a un'API REST è composta dai seguenti componenti:

• Punto finale: Ogni richiesta API viene indirizzata a un endpoint API, che è un URL dedicato che fornisce l'accesso a una risorsa specifica. Ad esempio, l'endpoint /products in un'app di e-commerce includerebbe la logica per l'elaborazione di tutte le richieste correlate ai prodotti. La richiesta deve quindi designare un endpoint in modo che il server API sappia come procedere. Discuteremo presto del server API in modo più dettagliato.
• Metodo: Ogni richiesta API deve includere un metodo, che definisce l'operazione che il client vorrebbe eseguire sulla risorsa specificata. Le API REST sono accessibili tramite metodi HTTP standard, come GET, POST, PUT, PATCH e DELETE, che facilitano azioni comuni come il recupero, la creazione, l'aggiornamento o l'eliminazione dei dati. Una richiesta GET all'endpoint /products direbbe al server API di restituire ogni prodotto nel database.
• Parametri: i parametri sono le variabili che vengono passate a un endpoint API per fornire istruzioni specifiche per l'elaborazione da parte dell'API. Questi parametri possono essere inclusi nella richiesta API come parte dell'URL, nella stringa di query o nel corpo della richiesta. Ad esempio, l'endpoint /products di un'API di e-commerce potrebbe accettare un parametro "color", che utilizzerebbe per accedere e restituire prodotti di un colore specifico.
• Richiedi intestazioni: le intestazioni della richiesta API sono coppie chiave-valore che forniscono informazioni aggiuntive sulla richiesta. Ad esempio, l'intestazione Content-Type specifica il formato dei dati nel corpo della richiesta, mentre l'intestazione Authorization fornisce le credenziali di autenticazione, come una chiave API o un token OAuth, per autenticare il richiedente.
• Corpo della richiesta: Il corpo della richiesta include i dati effettivi necessari per creare, aggiornare o eliminare una risorsa. Ad esempio, se un amministratore di un negozio di e-commerce deve creare un nuovo prodotto, il corpo della richiesta potrebbe includere il nome, la marca e il prezzo del prodotto. La specifica dell'API determinerà il formato dei dati richiesto per la richiesta, ad esempio JSON o XML.

Server dell'API

Dopo che il client API ha assemblato la richiesta, la invia all'endpoint appropriato sul server API per l'elaborazione. Il server API è responsabile della gestione dell'autenticazione, della convalida dei dati di input, del recupero o della manipolazione dei dati da un database e della restituzione della risposta appropriata al client.

È importante notare che mentre il database stesso non è un componente API, l'API non può funzionare senza di esso. Mentre il server API recupera e manipola i dati dell'applicazione in base a una richiesta, il database archivia e organizza questi dati in modo da facilitare il recupero e la manipolazione efficienti. Il server API funge quindi da intermediario tra il client API e il database.

Risposta dell'API

Abbiamo menzionato sopra che il server API è responsabile dell'invio di una risposta al client dopo che ha elaborato la richiesta. Il contenuto delle risposte API può variare notevolmente a seconda del tipo di richiesta e del design dell'API, ma in genere includono i seguenti componenti:

• Codice di stato: I codici di stato API sono codici di stato HTTP restituiti da un'API per indicare lo stato della richiesta di un client. Questi codici vengono utilizzati per fornire informazioni al cliente sull'esito della richiesta e per aiutare il cliente a capire come procedere. Alcuni dei codici di stato più comuni includono 200 OK, che indica che il server ha restituito correttamente i dati richiesti, 201 Created, che indica che il server ha creato correttamente una nuova risorsa e 404 Not Found, che indica che il server non è riuscito a trovare la risorsa richiesta risorsa.
• Intestazioni di risposta: Le intestazioni di risposta sono molto simili alle intestazioni di richiesta, tranne per il fatto che vengono utilizzate per fornire informazioni aggiuntive sulla risposta del server. Ad esempio, l'intestazione Cache-Control fornisce istruzioni per quanto tempo i dati possono essere archiviati in una cache, mentre l'intestazione Set-Cookie imposta un cookie nel browser, che può essere utilizzato per la gestione della sessione o l'autenticazione.
• Corpo della risposta: Il corpo della risposta contiene i dati o il contenuto che viene restituito dal server API in risposta alla richiesta del client. I corpi delle risposte variano notevolmente, ma in genere includono oggetti di dati strutturati che rappresentano le risorse richieste, i metadati e, se la richiesta non è andata a buon fine, messaggi di errore su ciò che è andato storto. Ad esempio, una richiesta GET riuscita per un prodotto specifico potrebbe includere una rappresentazione JSON di tale prodotto, nonché un timestamp e l'origine dei dati.

Mentre REST è l'architettura API più comune, altri tipi di API, come GraphQL e gRPC, avranno componenti diversi. Tuttavia, questo elenco include i componenti principali coinvolti nell'esecuzione delle richieste a ogni API RESTful.

Oggi, decine di migliaia di sviluppatori utilizzano la piattaforma Apitgit. Apitgit semplifica ogni fase del ciclo di vita dell'API e semplifica la collaborazione in modo da poter creare API migliori, più velocemente.