Concetti di API Gateway

Nel servizio Gateway API, un gateway API è un'appliance di rete virtuale in una subnet regionale.

Un gateway API instrada il traffico in entrata ai servizi backend, incluse le API HTTP pubbliche, private e dei partner, nonché le funzioni OCI. Ogni gateway API è un endpoint privato che è possibile esporre facoltativamente su un indirizzo IP pubblico come gateway API pubblico:

• L'accesso a un gateway API privato può essere eseguito solo dalle risorse nella stessa rete privata (VCN) o dalle risorse in un'altra rete privata o on premise gestita in peering su tale rete privata. Un gateway API privato dispone di un indirizzo IP privato e di un nome host generato automaticamente nel formato <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Si noti che, sebbene il nome host sia risolvibile pubblicamente da Internet, si risolve nell'indirizzo IP privato del gateway API. Il traffico verso l'indirizzo IP privato non è instradabile dalla rete Internet pubblica; solo i client all'interno della VCN possono accedere al gateway API. La possibilità di risoluzione DNS pubblica di un indirizzo IP privato è prevista, supportando varie configurazioni di rete all'interno degli ambienti OCI.
• Un gateway API pubblico è accessibile pubblicamente e può essere raggiunto da Internet, a condizione che sia presente un gateway Internet nella VCN del gateway API. Un gateway API pubblico ha sia un indirizzo IP privato che un indirizzo IP pubblico e un nome host generato automaticamente nel formato <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Il nome host generato viene risolto da Internet all'indirizzo IP pubblico, consentendo ai client basati su Internet di accedere al gateway API.

Per garantire l'alta disponibilità, puoi creare gateway API solo nelle subnet regionali (non nelle subnet specifiche di AD). Puoi creare gateway API privati in subnet private o pubbliche, ma puoi creare solo gateway API pubblici in subnet pubbliche. Il servizio gateway API è di tipo regionale e tollerante agli errori nei domini di disponibilità (in più aree AD) e nei domini di errore (in singole aree AD). In più aree AD, il servizio Gateway API seleziona automaticamente un dominio di disponibilità attivo per arrestare l'endpoint del gateway API. Tenere presente che, a seconda dell'origine e della destinazione del traffico, il traffico potrebbe essere instradato tra i domini di disponibilità. Se un dominio di disponibilità o un dominio di errore non riesce, il servizio gateway API gestisce automaticamente il failover e instrada il traffico verso un dominio di disponibilità o un dominio di errore funzionante.

Un gateway API è associato a una VNIC specifica.

Puoi creare un gateway API all'interno di un compartimento nella tua tenancy. Ogni gateway API ha un unico front-end, zero o più back-end e ha zero o più API distribuite su di esso come distribuzioni API.

Nel servizio Gateway API, un'API è un set di risorse backend e i metodi (ad esempio, GET, PUT) che possono essere eseguiti su ogni risorsa backend in risposta alle richieste inviate da un client API.

Per abilitare un gateway API per elaborare le richieste API, è necessario distribuire l'API nel gateway API creando una distribuzione API.

Per distribuire un'interfaccia API su un gateway API, è possibile creare una risorsa API nel servizio Gateway API. Una risorsa API include una descrizione API che definisce la risorsa API. Tenere presente che la creazione di una risorsa API è facoltativa. Puoi distribuire un'interfaccia API su un gateway API senza creare una risorsa API nel servizio API Gateway.

Nel servizio API Gateway, la distribuzione di un'interfaccia API consente di distribuire un'interfaccia API su un gateway API. Prima che il gateway API possa gestire le richieste all'API, è necessario creare una distribuzione API.

Quando si crea una distribuzione API, si impostano le proprietà per la distribuzione API, inclusa una specifica di distribuzione API. Ogni distribuzione API ha una specifica di distribuzione API.

Puoi distribuire più API sullo stesso gateway API, in modo che un singolo gateway API possa ospitare più distribuzioni API.

Nel servizio Gateway API, una specifica di distribuzione API descrive alcuni aspetti della distribuzione di un'API.

Quando si crea la distribuzione API, si impostano le proprietà per la distribuzione API, inclusa una specifica di distribuzione API. Ogni distribuzione API ha una specifica di distribuzione API. È possibile creare una specifica di distribuzione API:

• mediante finestre di dialogo nella console
• utilizzando l'editor JSON preferito per creare un file JSON
• utilizzando una descrizione API caricata da un file di descrizione API scritto in una lingua supportata (ad esempio, OpenAPI Specifica versione 3.0)

Ogni specifica di distribuzione API descrive una o più risorse backend, l'instradamento a ogni risorsa backend e i metodi (ad esempio, GET, PUT) che possono essere eseguiti su ogni risorsa. La specifica di distribuzione API descrive il modo in cui il gateway API si integra con il backend per eseguire tali metodi. La specifica di distribuzione API può includere anche criteri di richiesta e risposta.

Nel servizio Gateway API è possibile creare una risorsa API. Una risorsa API è la rappresentazione in fase di progettazione di un'API. È possibile utilizzare una risorsa API per distribuire un'API in un gateway API.

Una descrizione API definisce una risorsa API, tra cui:

• endpoint disponibili
• operazioni disponibili su ogni endpoint
• parametri che possono essere di input e output per ogni operazione
• metodi di autenticazione

Se si utilizza una risorsa API per distribuire un'interfaccia API su un gateway API, la relativa descrizione popola preventivamente alcune delle proprietà della specifica di distribuzione API.

La descrizione dell'API viene importata da un file (a volte denominato 'Specifica API' o 'Specifica API') scritto in una lingua supportata. Attualmente sono supportate le specifiche OpenAPI versione 2.0 (precedentemente Swagger Specification 2.0) e versione 3.0.

È inoltre possibile generare un SDK dal file di descrizione dell'API.

Tenere presente che la creazione di una risorsa API nel servizio Gateway API è facoltativa. Puoi distribuire un'interfaccia API su un gateway API senza creare una risorsa API nel servizio API Gateway. Tenere inoltre presente che è possibile creare una risorsa API che inizialmente non dispone di una descrizione API, quindi aggiungere una descrizione API in un secondo momento.

Nel servizio Gateway API, un front-end è il mezzo con cui le richieste fluiscono in un gateway API. Un gateway API può avere un front end pubblico o un front end privato:

• Un front end pubblico espone le API distribuite su un gateway API tramite un indirizzo IP pubblico.
• Un frontend privato espone le API distribuite in un gateway API a una VCN tramite un endpoint privato.

Nel servizio Gateway API, un backend è il mezzo con cui un gateway instrada le richieste ai servizi backend che implementano le API. Se si aggiunge un backend di endpoint privato a un gateway API, si concede al gateway API l'accesso alla VCN associata a tale endpoint privato.

Puoi anche concedere a un gateway API l'accesso ad altri servizi Oracle Cloud Infrastructure come back-end. Ad esempio, puoi concedere a un gateway API l'accesso a OCI Functions, in modo da poter creare e distribuire un'API supportata da una funzione serverless.

Un provider API è una persona o un team che progetta, implementa, distribuisce e gestisce le API. Questi utenti interagiscono con interfacce quali la console di Oracle Cloud Infrastructure, l'SDK, l'interfaccia CLI e il provider Terraform. Utilizza il servizio Gateway API per distribuire, monitorare e gestire le API. Alcune organizzazioni segmentano ulteriormente il ruolo del provider API, ad esempio in:

• Sviluppatori di API, con la responsabilità di creare API e distribuirle sui gateway API.
• Manager piani API, con responsabilità per il monitoraggio e la gestione dell'uso delle API, ad esempio mediante la definizione di piani di utilizzo e sottoscrittori.
• Manager gateway API, con responsabilità per l'amministrazione dei gateway API, in genere in produzione.

Un consumer API è una persona o un team che crea applicazioni e servizi (client API) e desidera sfruttare una o più API offerte da un provider API. Il consumer API in genere non condivide una tenancy Oracle Cloud Infrastructure con il provider API. Il consumer API è un cliente del provider API.

Un client API è un'applicazione o un dispositivo creato da un consumer API. Il client API richiama l'API in fase di runtime inviando richieste al gateway API su cui viene distribuita l'API. I client API comunicano con il gateway API tramite HTTPS (incluso HTTP/2). I client API in genere eseguono l'autenticazione con l'API utilizzando OAuth, l'autenticazione di base e mTLS e potrebbero utilizzare altri token, ad esempio una chiave API per la misurazione e la monetizzazione.

Un utente finale è un utente di un client API e talvolta viene definito "proprietario delle risorse" in termini di autorizzazione. L'utente finale interagisce solo con un'API utilizzando il client API ed è in genere inconsapevole dell'API stessa. L'utente finale è un cliente del consumer API.

Nel servizio Gateway API, i responsabili dei piani API possono gestire e monitorare l'uso delle proprie API definendo le risorse del piano di utilizzo e degli abbonati.

Una risorsa del piano di utilizzo comprende le abilitazioni. Ogni abilitazione specifica:

• Limite di frequenza: il numero massimo di richieste API consentite al secondo.
• Quota: il numero totale di chiamate API consentite in un determinato periodo di tempo (tra un minuto e un mese).
• Una o più distribuzioni API di destinazione. Le distribuzioni API a cui possono accedere i sottoscrittori del piano di utilizzo.

È possibile specificare una distribuzione API come destinazione in più abilitazioni in piani di utilizzo diversi, ma non in più abilitazioni nello stesso piano di utilizzo. Un'abilitazione può includere distribuzioni API da gateway API diversi.

In qualità di manager dei piani API, i piani di utilizzo consentono di controllare l'accesso API disponibile per i clienti (utenti API) e i relativi client API. È possibile sottoporre l'accesso all'API a limiti di tariffa e quote personalizzati in base a specifiche esigenze dei clienti, consentendo di impostare livelli di accesso diversi per clienti diversi.

Una risorsa sottoscrittore comprende:

• Un singolo consumer API.
• Nomi client e token client per identificare in modo univoco i client API creati dal consumer API.
• Piani di utilizzo ai quali sono sottoscritti il consumer API e i relativi client API.

I manager dei piani API possono creare sottoscrittori per i clienti (consumatori API) per specificare i piani di utilizzo che consentono ai client API di accedere alle API.

Per rendere una distribuzione API idonea per l'inclusione in un piano di utilizzo, specificare la posizione del token client passato nelle richieste. Una volta inclusa la distribuzione API in un piano di utilizzo, le richieste devono includere il token client in questa posizione per accedere alla distribuzione API. Specificare la posizione del token client in un criterio di richiesta del piano di utilizzo nella specifica di distribuzione API. Tenere presente che i token client definiti nelle risorse del sottoscrittore sono solo a scopo di report del piano di utilizzo e non per l'autenticazione e l'autorizzazione del client.

Nel servizio gateway API, un instradamento è il mapping tra un percorso, uno o più metodi e un servizio backend. Gli instradamenti sono definiti nelle specifiche di distribuzione API.

Nel servizio Gateway API esistono diversi tipi di criteri:

• un criterio di richiesta descrive le azioni da eseguire su una richiesta in entrata da un client API prima che venga inviata a un backend
• un criterio di risposta descrive le azioni da eseguire su una risposta restituita da un backend prima di essere inviata a un client API
• un criterio di log descrive come memorizzare informazioni su richieste e risposte che passano attraverso un gateway API e informazioni sull'elaborazione all'interno di un gateway API

È possibile utilizzare i criteri di richiesta e/o di risposta per:

• limitare il numero di richieste inviate ai servizi backend
• abilitare il supporto CORS (Cross-Origin Resource Sharing)
• fornire autenticazione e autorizzazione
• convalidare le richieste prima di inviarle ai servizi backend
• modificare le richieste in entrata e le risposte in uscita
• rendere le distribuzioni API idonee per l'inclusione nei piani di utilizzo che monitorano e gestiscono l'accesso degli iscritti

È possibile aggiungere criteri a una specifica di distribuzione API che si applicano a livello globale a tutti gli instradamenti nella specifica di distribuzione API, nonché criteri che si applicano solo a determinati instradamenti.

I criteri del gateway API sono diversi dai criteri IAM che controllano l'accesso alle risorse di Oracle Cloud Infrastructure.