Che cos'è un endpoint API? Guida al software connesso

Un endpoint API (Application Programming Interface) è l'URL specifico in cui un'API riceve richieste e restituisce risposte.

Gli endpoint API sono l'indirizzo web esatto in cui un'applicazione si connette a un server per richiedere dati o eseguire un comando. Sebbene vengano ancora utilizzate architetture tradizionali, le applicazioni moderne si basano su API REST per gestire richieste HTTP tra servizi diversi.

Questa guida spiega come gli endpoint elaborano le richieste, come formattare le chiamate e come mantenere sicuri gli endpoint API negli ambienti di produzione. Ti mostreremo anche come connettere facilmente i tuoi sistemi con ElevenAPI e distribuire workflow audio pronti per la produzione.

In sintesi

• Un endpoint API è l'URL specifico in cui un'API riceve richieste e restituisce risposte.
• Configurare percorsi di comunicazione automatizzati tra applicazioni client e infrastruttura server riduce gli attriti nello scambio di dati e nell'integrazione dei sistemi.
• I sette tipi di API più comuni includono endpoint API REST, SOAP, GraphQL, RPC, WebSocket, gRPC e API Web.
• Tra le best practice più comuni per la progettazione degli endpoint API ci sono una denominazione intuitiva basata sulle risorse e l'abbinamento di codici di stato HTTP standardizzati a payload di errore JSON strutturati.
• I team di ingegneria testano e monitorano gli endpoint API convalidando i codici HTTP, verificando la connettività di base delle richieste e monitorando la concorrenza in tempo reale.
• Per proteggere gli endpoint API servono autenticazione basata su chiavi, definizione dei permessi secondo il principio del privilegio minimo e rate limit basati sulla concorrenza.

Endpoint API spiegati: richieste, risposte e route

Un endpoint API è una posizione digitale che un'API usa per ricevere richieste e restituire risposte. Le applicazioni client usano un URL specifico associato a questo endpoint per accedere alle risorse del server.

Ogni route dell'endpoint gestisce un'interazione distinta abbinando un metodo HTTP a un path di risorsa. Il client invia una richiesta a quella route e il server elabora i dati prima di inviare una risposta con un codice di stato.

Ad esempio, quando un'applicazione richiede metadati utente o invia un payload di dati, manda una richiesta HTTP a un URL dell'endpoint designato e fornito dal server API.

API, endpoint e URL: qual è la differenza?

Sebbene i termini API, endpoint API e URL vengano spesso usati insieme, rappresentano componenti distinti dell'architettura software.

Un'API fornisce l'interfaccia software completa che definisce le regole e i protocolli per la comunicazione tra due applicazioni. Un endpoint API, invece, funge da punto di accesso digitale specifico su un server, usato dalle app per la comunicazione bidirezionale. Infine, un URL è la stringa completa dell'indirizzo web che le applicazioni client usano per individuare e connettersi a quell'endpoint tramite la rete.

Le principali differenze tra API, endpoint e URL includono:

• Ambito e architettura: un'API comprende l'intero sistema di regole e contratti di dati, mentre l'endpoint API riguarda una sola posizione specifica e l'URL è l'indirizzo di tale posizione.
• Funzione e scopo: un'API specifica come i componenti software interagiscono tra loro, mentre gli endpoint API danno accesso a una funzione o risorsa di dati specifica e l'URL indica con precisione all'applicazione client dove indirizzare la chiamata.
• Composizione: un'API ha più endpoint, ma un endpoint API abbina uno specifico path di risorsa a un metodo HTTP. Un URL include inoltre molte parti, come il protocollo di rete, il nome di dominio, il path dell'endpoint e i parametri di query.

Come funzionano gli endpoint API?

Gli endpoint API usano un ciclo strutturato di richiesta e risposta tra applicazioni client e server, che in genere segue questi passaggi:

1. Avvio: il client invia una richiesta HTTP direttamente all'URL dell'endpoint. Questa richiesta include un metodo HTTP, header HTTP, parametri di query facoltativi e dati facoltativi nel body della richiesta.
2. Convalida ed elaborazione: il server riceve la richiesta, autentica le credenziali del client e verifica i permessi di accesso. Il sistema backend interroga quindi i database interni o esegue la logica di business lato server per elaborare l'operazione richiesta.
3. Invio della risposta: il server raccoglie l'output in un payload JSON strutturato. Invia questo payload al client insieme a un codice di stato HTTP che conferma l'esecuzione riuscita o fornisce dettagli sugli errori generati.
4. Esecuzione dell'integrazione: l'applicazione client analizza il payload restituito per aggiornare le interfacce utente, elaborare i dati e attivare azioni successive.

Endpoint API REST e metodi HTTP utilizzati

Gli endpoint API REST usano metodi HTTP standard per definire le azioni che i client eseguono su una risorsa del server. Le richieste GET leggono i dati e non apportano modifiche alle risorse backend. Al contrario, le richieste POST scrivono dati inviando nuovi dati per creare risorse o attivare azioni lato server.

Inoltre, gli sviluppatori usano richieste PUT o PATCH per modificare record esistenti e DELETE per rimuovere risorse specifiche dal database. 

In ElevenAPI, le integrazioni si basano principalmente su richieste GET e POST, oltre che su endpoint di streaming e WebSocket per l'audio in tempo reale. Gli endpoint GET recuperano i metadati disponibili di voci e modelli, mentre quelli POST eseguono attività di generazione, come la sintesi Text to Speech.

Esempi di endpoint API: uno sguardo pratico alle richieste comuni

Esaminare richieste reali in ElevenAPI illustra come funzionano gli endpoint API negli ambienti di produzione. 

Con ElevenAPI, ogni route dell'endpoint corrisponde a metodi HTTP specifici che svolgono determinate attività, come recuperare metadati di sistema o generare audio. Le applicazioni client inviano richieste GET per recuperare informazioni e richieste POST per inviare dati ed eseguire attività di elaborazione. 

Ecco come funzionano queste route principali in produzione.

Richiesta di lettura

GET https://api.elevenlabs.io/v1/models recupera un elenco dei modelli di sintesi vocale disponibili e delle relative capacità. Questa richiesta richiede l'header HTTP xi-api-key per l'autenticazione, ma non richiede un body della richiesta. Il server elabora la query e restituisce un payload JSON contenente i dettagli del modello.

Richiesta di scrittura

POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} invia dati payload al server per generare audio. La tua applicazione invia un body JSON contenente parametri, come text e model_id, per eseguire la sintesi Text to Speech. L'endpoint elabora questi parametri e trasmette in streaming l'audio formattato alla tua applicazione.

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128" \
     -H "xi-api-key: xi-api-key" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_multilingual_v2"
}'

Scopri di più nel Riferimento API di Text to Speech.

I sette tipi di API più comuni e quando usarli

I team di sviluppo scelgono tra sette architetture API comuni e prendono decisioni in base alle proprie esigenze di trasferimento dati. 

ElevenAPI combina diversi stili architetturali in un'unica piattaforma per massimizzare l'efficienza e ridurre al minimo la latenza. In genere, usa REST per le richieste standard e protocolli WebSocket per lo streaming audio in tempo reale.

Best practice per progettare endpoint API e integrazioni prevedibili

L'uso delle best practice di progettazione mantiene gli endpoint API stabili, manutenibili e resilienti anche quando le piattaforme sottostanti cambiano e i casi d'uso aumentano. ElevenAPI usa regole REST chiare per semplificare l'integrazione per i team di ingegneria, tra cui:

• Nomi e versionamento intuitivi basati sulle risorse: Gli endpoint dovrebbero usare path basati su nomi e denominati direttamente in base alla risorsa che forniscono, quindi associarli a metodi HTTP espliciti per le azioni. Ad esempio, /v1/models or /v1/text-to-speech/{voice_id}.
• Codici di stato HTTP standardizzati e payload di errore strutturati: gli endpoint prevedibili restituiscono codici di stato HTTP standard per indicare l'esito esatto di una richiesta. Abbinare questi codici di stato a payload di errore JSON strutturati consente al software client di decidere programmaticamente se correggere i parametri della richiesta o eseguire nuovi tentativi con backoff.
• SDK type-safe e convalida dei parametri SDK: offrire SDK ufficiali e fortemente tipizzati in linguaggi come Python e TypeScript semplifica l'integrazione. Questo metodo applica inoltre gli schemi delle richieste prima che le chiamate di rete lascino il client.

Come testare e monitorare gli endpoint API

Testare gli endpoint API nelle fasi iniziali conferma l'autenticazione e convalida la connettività di rete prima che gli sviluppatori scrivano la logica dell'applicazione. 

Invia una richiesta a GET https://api.elevenlabs.io/v1/models (oppure esegui curl https://api.elevenlabs.io/v1/models) usando l'header HTTP xi-api-key per convalidare le credenziali, verificare l'accesso alla rete e restituire i modelli disponibili. 

Quindi, monitora il traffico in tempo reale e tieni d'occhio le risposte di errore HTTP 429. I team di ingegneria monitorano le metriche per individuare picchi di utilizzo imprevisti e adeguare di conseguenza la frequenza delle richieste in uscita.

Un errore too_many_concurrent_requests indica che un account ha raggiunto il limite di concorrenza del proprio piano, quindi attendi che le richieste in corso terminino oppure passa a un piano superiore. Al contrario, un errore system_busy indica che la piattaforma sta subendo una congestione temporanea. In genere, riprovando la richiesta l'operazione riesce.

Sicurezza degli endpoint API: autenticazione, autorizzazione e rate limit

Proteggere gli endpoint API richiede di salvaguardare le credenziali segrete e al tempo stesso stabilire limiti granulari su ciò che ogni credenziale può fare. ElevenAPI usa tre meccanismi fondamentali, oltre alle best practice consigliate, per proteggere le operazioni backend e le integrazioni client.

1. Autenticazione

Ogni richiesta include l'header HTTP xi-api-key con la credenziale segreta. Le chiavi API a lunga durata devono rimanere rigorosamente su server sicuri e non devono essere esposte nel codice lato client, ad esempio in browser o app mobile. Per le connessioni WebSocket lato client di Scribe e Text to Speech, il tuo server genera un token monouso, così la chiave a lunga durata rimane protetta.

I token monouso scadono dopo 15 minuti e vengono utilizzati al primo impiego. Scopri di più nella documentazione sui token monouso.

2. Autorizzazione e ambito

Crea chiavi separate per gli ambienti di sviluppo, staging e produzione. Quindi, configura ciascuna chiave in base a questi tre meccanismi di sicurezza granulari:

• Accesso agli endpoint: Limita gli endpoint specifici che un'API può chiamare, in modo che ogni credenziale disponga soltanto dell'autorizzazione necessaria per l'attività che esegue. Ad esempio, una chiave dedicata alla trascrizione Speech to Text non necessita dell'accesso alla generazione Text to Speech.
• Quote di crediti: assegna limiti di credito personalizzati per ogni chiave per limitare l'esposizione finanziaria derivante da un consumo inaspettatamente elevato, contenere i loop di esecuzione nel codice dell'applicazione e proteggere i saldi dell'account in caso di fuga di una chiave.
• Allowlist degli IP: gli account enterprise possono limitare l'uso delle chiavi a indirizzi IP o intervalli CIDR specifici (attualmente in anteprima, disponibile tramite il tuo account manager). Le richieste provenienti da qualsiasi altro IP vengono rifiutate con un errore HTTP 403.

Rate limit

I rate limit si basano sulla concorrenza anziché su semplici quote al minuto. Limitano il numero di generazioni simultanee o richieste in corso eseguite contemporaneamente per specifiche famiglie di modelli.

Crea workflow vocali e di IA conversazionale con ElevenAPI

ElevenAPI offre accesso programmatico a una suite completa di funzionalità audio IA, tra cui Voice Agents, Text to Speech e Speech to Text. Con bassa latenza, elevata espressività emotiva e supporto per oltre 90 lingue nella sua suite di modelli, ElevenAPI integra audio simile a quello umano direttamente nel tuo tech stack. Così ampli le capacità della tecnologia alla base delle tue soluzioni aziendali nel supporto clienti, nella formazione dei dipendenti, nella produzione di contenuti e nel marketing.

Che tu stia implementando agenti conversazionali in tempo reale o automatizzando la localizzazione multilingue, ElevenAPI fornisce l'infrastruttura, la velocità e la sicurezza richieste dalle applicazioni di produzione. 

Esplora ElevenAPI per consultare i riferimenti degli endpoint e i cookbook di integrazione oppure richiedi una chiave API per iniziare a sviluppare oggi stesso.

Domande frequenti sugli endpoint API