Cos'è un endpoint API?

Un'API è un intermediario che consente alle applicazioni software di comunicare tra loro per scambiare dati, caratteristiche e funzionalità. È un insieme di protocolli e regole che definiscono il modo in cui un client API, il software che effettua una richiesta, può comunicare con un server per accedere a dati e funzioni. Utilizzando un'API, gli sviluppatori possono utilizzare i dati e i servizi già esistenti, mentre i proprietari delle applicazioni possono condividerli o commercializzarli.

Gli endpoint funzionano un po' come i numeri di telefono: proprio come un utente compone un numero di telefono per contattare una determinata persona o azienda, i client API (il software che effettua una chiamata API) forniscono un URL dell'endpoint per raggiungere una risorsa specifica. L'URL di un endpoint fornisce la posizione di una risorsa su un server API e aiuta a connettere il client API con la risorsa richiesta. In sostanza, dice al server: "La risorsa di cui ho bisogno si trova qui".

Gli endpoint API possono consentire a un client API di richiedere qualsiasi tipo di dati da un'API, con casi d'uso che vanno dagli aggiornamenti in tempo reale delle applicazioni software di social media a funzionalità come l'embedding di audio o video, fino al recupero di notizie o la creazione di un nuovo post.

Gli endpoint API correttamente formattati e sicuri sono una parte cruciale del funzionamento delle API. Le API semplificano la progettazione e lo sviluppo di nuovi servizi e applicazioni (poiché consentono ai sviluppatori di costruire su funzionalità e servizi esistenti) e l'integrazione e la gestione di quelli esistenti. Offrono inoltre vantaggi significativi agli sviluppatori e alle organizzazioni in generale, tra cui una migliore collaborazione, un'innovazione accelerata, una maggiore agilità, scalabilità, sicurezza e altro ancora. Gli endpoint API consentono lo scambio di risorse che rende possibile tale integrazione.

Perché le API funzionino correttamente, i loro endpoint devono essere precisi, intuitivi, rilevabili e autenticati, altrimenti la comunicazione tra client e server può interrompersi, portando via con sé le funzionalità e la soddisfazione dell'utente. In poche parole, gli endpoint API consentono ai client API di individuare e accedere correttamente alle risorse e alle funzioni richieste.

Gli endpoint API si trovano solitamente nella documentazione di un'API, che è il luogo in cui gli sviluppatori inseriscono le informazioni API, ad esempio il tipo di richieste che un'API accetterà e il modo in cui le richieste devono essere formattate. Idealmente, questa documentazione include anche un elenco di tutti gli endpoint API disponibili e una breve descrizione delle loro funzionalità.

Nel contesto di un' API REST (uno stile di architettura software spesso utilizzato per le applicazioni web), il processo si presenta così:

Il processo inizia quando un client API invia una richiesta di risorse (chiamata API) all'endpoint API corrispondente. L'accesso agli endpoint avviene tramite metodi di richiesta HTTP, ad esempio POST, GET, PUT, PATCH e DELETE. Questi metodi indicano l'azione che il client sta cercando di eseguire sulla risorsa specificata.

Ad esempio, se un client sta cercando di recuperare un elenco delle medaglie olimpiche totali per un determinato anno dall'ipotetico database OlympicFacts.com, viene inviata una richiesta GET all'URL dell'endpoint seguente: 

https://api.olympicfacts.com/v1/{year}

Questa richiesta restituirà un elenco di medaglie olimpiche per paese. (v1 nel nostro ipotetico endpoint indica la versione dell'API, una pratica comune nel versioning delle API). Se il client desiderasse un totale per un paese specifico in un determinato anno, verrebbe aggiunto un identificatore all'URL di base: 

https://api.olympicfacts.com/v1/year/{id}

In questo esempio, l'identificatore {id} viene utilizzato per indicare il paese su cui il cliente sta cercando di ricevere informazioni.

Inoltre, una richiesta potrebbe includere:

• Intestazioni: le intestazioni possono fornire informazioni aggiuntive sulla richiesta, come l'intestazione Accept che specifica i tipi di media accettati
  
  
• Parametri: i parametri della query possono essere aggiunti all'URL di base o nel corpo della richiesta per filtrare ulteriormente i criteri di ricerca o aggiungere altre specifiche.
  
  
• Corpo della richiesta: un corpo della richiesta include i dati necessari per creare o modificare una risorsa. Ad esempio, se la richiesta è quella di creare un nuovo blog (richiesta POST), il contenuto del nuovo blog verrà incluso nel corpo della richiesta.
  

Una volta che il server ha autenticato la richiesta e convalidato l'input, recupera i dati richiesti e restituisce la risposta al cliente. Molte organizzazioni utilizzano gli API gateway per eseguire queste funzioni e gestire il flusso del traffico API.

Un'API REST (chiamata anche API RESTful o API web RESTful) è un'API conforme ai principi di progettazione dello stile architetturale REST (Representational State Transfer ).¹ GraphQL è un linguaggio di query open source e un runtime lato server che specifica come i clienti devono interagire con le API.²

GraphQL e REST sono entrambe tecnologie basate su risorse che supportano formati di dati simili (JSON e XML, ad esempio) e consentono ai client di richiedere dati dai server utilizzando metodi HTTP. Tuttavia, differiscono tra loro, tra le altre cose, per quanto riguarda i requisiti di richiesta e il recupero dei dati. Ci concentreremo su una differenza chiave relativa agli endpoint.

Le API REST usano più endpoint e hanno endpoint diversi per ogni risorsa. Quando un client richiede una risorsa, il server restituisce tutti i dati associati alla risorsa, anche se il client ha bisogno solo di un piccolo sottoinsieme dei dati. Questo fenomeno è noto come overfetching. Se un client ha bisogno di dati distribuiti su più risorse, deve effettuare chiamate API separate a ciascuna di queste risorse per compilare i dati necessari.

GraphQL espone i modelli di dati utilizzando un singolo endpoint e utilizza una sintassi che consente ai clienti di effettuare richieste API in una sola riga, o in poche righe, per specificare esattamente ciò di cui hanno bisogno. Le query GraphQL possono seguire i riferimenti tra le risorse e soddisfare compiti complessi di recupero dei dati in un'unica richiesta. Questo aiuta a eliminare i problemi di under e overfetching e la necessità di effettuare più chiamate API.

Né le API REST, né le API GraphQL sono intrinsecamente superiori; sono strumenti diversi, adatti a compiti diversi.³

La fase di test è fondamentale per una buona progettazione di qualsiasi API. Le applicazioni moderne spesso utilizzano le API per integrare funzioni di altri software oppure sono realizzate utilizzando architetture di microservizi (che si basano sulle API per la comunicazione tra servizi diversi). Testare gli endpoint API è essenziale per garantire l'affidabilità.

Per le API, esistono sia opzioni di test manuali che opzioni di test che utilizzano l'automazione, oltre a numerosi strumenti e piattaforme di test (sia open source che proprietarie) disponibili per le aziende.

Il test manuale degli endpoint API può essere più lento e meno efficiente, ma anche più preciso e personalizzato in base a casi d'uso specifici. Il test funzionale consiste semplicemente nell'inviare una richiesta da un'applicazione per assicurarsi che venga data la risposta corretta. Nell'esempio di un social media, ciò potrebbe significare inviare una richiesta per un nuovo post da parte di un determinato utente e verificare che il post restituito sia effettivamente quello corretto.

Altri tipi di test manuali riguardano: 

• inviare molte richieste contemporaneamente per vedere come il server gestisce il carico di richieste
  
  
• verificare che l'API si integri correttamente con altri servizi
  
  
• determinare la velocità e il tempo di risposta di una determinata richiesta
  
  
• fornire intenzionalmente una richiesta non valida per verificare che venga restituito il giusto messaggio di errore

Eseguire test automatizzati attraverso un'API management platform può offrire diversi vantaggi:

• riduce la possibilità di errore umano
  
  
• è più efficiente nel controllare la validità di più endpoint API
  
  
• può migliorare la velocità dei test e potenzialmente ridurre i costi a lungo termine una volta impostati i sistemi di test automatici (risparmiando tempo per i dipendenti, ad esempio)
  
  
• Allinea i test secondo protocolli, standard e autorizzazioni uniformi

In generale, ognuno dovrebbe restituire la risposta prevista, in termini di formato, dati restituiti e codice di stato.

Poiché gli endpoint API forniscono alle applicazioni e ai sistemi interni ed esterni un modo per accedere ai dati e integrarli, rappresentano anche un potenziale punto d'ingresso per i malintenzionati. Gli attacchi Distributed Denial-of-Service (DDoS) possono utilizzare richieste legittime, ma in quantità assurde, per intasare un server. Altri tipi di attacchi potrebbero tentare di utilizzare gli endpoint API per estrarre più informazioni di quelle che il client è autorizzato a ricevere o utilizzare gli endpoint API per installare malware o codice dannoso.

Esistono diversi modi in cui un'organizzazione può garantire la sicurezza degli endpoint API e la sicurezza generale delle API, tra cui:

I metodi di autenticazione, come l'autenticazione con chiave API e OAuth, assicurano che solo gli utenti autorizzati siano in grado di accedere ai dati.

HTTPS (una versione più sicura del protocollo Hypertext Transfer Protocol o HTTP) utilizza il Transport Layer Security (TLS) per crittografare le comunicazioni tra client e server. Ciò aumenta la sicurezza dei trasferimenti di dati.

Il rate limiting è un termine generale che si riferisce agli sforzi per impostare quantità massime di richieste, che possono aiutare a prevenire gli attacchi DDoS e a mantenere la stabilità del sistema. Limiti diversi possono essere applicati anche a diversi endpoint API.

Se gli attacchi vengono generati da un particolare luogo, è possibile utilizzare il geofiltering per bloccare o limitare l'accesso da tali posizioni.

Un API gateway è un livello software che funge da intermediario tra i dispositivi client e i server. Si tratta di un punto centrale che accetta tutte le chiamate API e le instrada ai servizi richiesti. Molte di queste funzioni di sicurezza (oltre alle funzioni di API monitoring and analytics) possono essere implementate all'interno di un API gateway; inoltre, l'uso di un gateway promuove l'applicazione coerente dei protocolli di sicurezza in un ambiente API.

Le risorse API sono set di dati o oggetti forniti dalle API. Le risorse variano in base all'API in questione, ma i tipi di contenuto includono testo, tabelle, file sorgente, audio, video, immagini, utenti, prodotti e molto altro.

Un endpoint API è la posizione specifica di tali risorse su un server. È un punto di contatto tra un client API e un server, dove vengono indirizzate le chiamate API.

Prendiamo in esempio un profilo aziendale di un negozio. Il profilo indica l'ubicazione del negozio (endpoint) e i dati di contatto per richiedere informazioni come gli orari del negozio e l'inventario dei prodotti (risorse).

Una chiave API è un metodo per verificare e autenticare l'identità e l'autenticità di un client che effettua una chiamata API. Le chiavi API sono stringhe di caratteri generati in modo casuale emesse da un provider API agli utenti API registrati. Quando un dispositivo client effettua una chiamata API, include la chiave API. L'API gateway o il server API che riceve la chiamata controlla innanzitutto la chiave per convalidare l'identità del cliente prima di soddisfare la richiesta API. Se la chiave non corrisponde a nessuna delle chiavi consentite, il server rifiuta la chiamata API ed emette un messaggio di rifiuto.

Le organizzazioni utilizzano le chiavi API per autenticare singoli clienti e progetti, tracciare e identificare i modelli di traffico, bloccare gli usi indesiderati e altro ancora.

Gli endpoint API, come già detto, fungono da interfaccia tra i client e i server, dove i client API indirizzano le richieste di determinati dati o funzioni da un'API. Le chiavi API possono essere utilizzate per migliorare la sicurezza dell'intero ambiente API di un'azienda e delle sue integrazioni API.