Best practice per la progettazione e lo sviluppo di proxy API

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

Lo scopo di questo documento è fornire una serie di standard e best practice per lo sviluppo con Apigee. Gli argomenti trattati qui includono progettazione, codifica, utilizzo dei criteri, monitoraggio e debug. Le informazioni sono state raccolte dall'esperienza degli sviluppatori che collaborano con Apigee per implementare programmi API di successo. Questo è un documento vivente e verrà aggiornato di tanto in tanto.

Oltre alle linee guida qui fornite, potrebbe esserti utile anche l'articolo Introduzione agli antipattern.

Standard di sviluppo

Commenti e documentazione

Fornisci commenti in linea nelle configurazioni ProxyEndpoint e TargetEndpoint. I commenti migliorano la leggibilità di un flusso, soprattutto se i nomi dei file di criteri non sono sufficientemente descrittivi per esprimere la funzionalità sottostante del flusso.
Scrivi commenti utili. Evita commenti evidenti.
Utilizza rientro, spaziatura, allineamento verticale e così via coerenti.

Codifica in stile framework

La codifica in stile framework prevede l'archiviazione di risorse proxy dell'API nel tuo sistema di controllo delle versioni da riutilizzare in ambienti di sviluppo locali. Ad esempio, per riutilizzare un criterio, archivialo nel controllo del codice sorgente in modo che gli sviluppatori possano sincronizzarlo e utilizzarlo nel proprio ambiente di sviluppo proxy.

Per abilitare DRY (don'lo stesso), dove possibile, le configurazioni dei criteri e gli script devono implementare funzioni specializzate e riutilizzabili. Ad esempio, un criterio dedicato per estrarre i parametri di ricerca dai messaggi di richiesta potrebbe essere chiamato ExtractVariables.ExtractRequestParameters.
Libera i criteri e le risorse inutilizzati (JavaScript, Java, Enabler e ) dai proxy API, in particolare le risorse di grandi dimensioni che potrebbero rallentare le procedure di importazione e deployment.

Convenzioni di denominazione

L'attributo del criterio name e il nome del file del criterio XML devono essere identici.
L'attributo Policy callout Script e name dello script e il nome del file della risorsa devono essere identici.
DisplayName deve descrivere con precisione la funzione del criterio a una persona che non ha mai lavorato con quel proxy API prima d'ora.
Assegna un nome ai criteri in base alla loro funzione. Apigee consiglia di stabilire una convenzione di denominazione coerente per i tuoi criteri. Ad esempio, utilizza prefissi brevi seguiti da una sequenza di parole descrittive separate da trattini. ad esempio, AM-xxx per il criterio AssignMessage. Consulta anche lo strumento Apigeelint.
Utilizza le estensioni appropriate per i file delle risorse, .js per JavaScript, .py per Python e .jar per i file JAR di Java.
I nomi delle variabili devono essere coerenti. Se scegli uno stile, ad esempio camelCase o under_score, utilizzalo in tutto il proxy API.
Se possibile, utilizza i prefissi delle variabili per organizzare le variabili in base allo scopo, ad esempio Consumer.username e Consumer.password.

Sviluppo proxy API

Considerazioni iniziali sulla progettazione

Per indicazioni sulla progettazione dell'API RESTful, scarica l'ebook Web API Design: The Missing Link.
Se possibile, sfrutta i criteri e le funzionalità di Apigee per creare proxy API. Evita di codificare tutta la logica proxy nelle risorse JavaScript, Java o Python.
Crea flussi in modo organizzato. Più flussi, ciascuno con una singola condizione, sono preferibile rispetto a più allegati condizionali agli stessi preflow e postflow.
Come 'failsafe', crea un proxy API predefinito con un ProxyEndpoint BasePath di /. Può essere utilizzato per reindirizzare le richieste API di base a un sito per sviluppatori, per restituire una risposta personalizzata o eseguire un'altra azione più utile rispetto a restituire l'impostazione predefinita messaging.adaptors.http.flow.ApplicationNotFound.

Utilizza le risorse TargetServer per disaccoppiare le configurazioni TargetEndpoint dagli URL concreti, supportando la promozione in ambienti diversi.
Consulta Bilanciamento del carico tra i server di backend.
Se disponi di più RouteRule, creane una come 'default', ovvero come una RouteRule senza condizione. Assicurati che la RouteRule predefinita sia definita per ultima nell'elenco delle route condizionali. Le routeRoute vengono valutate dall'alto verso il basso in ProxyEndpoint. Consulta la guida di riferimento alla configurazione del proxy API.
Dimensioni bundle API proxy: i pacchetti proxy API non possono superare 15 MB.
Controllo delle versioni dell'API: per i pensieri e i consigli di Apigee relativi al controllo delle versioni dell'API, consulta la sezione Versioning nell'ebook Web API Design: The Missing Link.

Abilitazione di CORS

Prima di pubblicare le API, devi aggiungere il criterio CORS al richieste PreFlow di ProxyEndpoint per supportare le richieste multiorigine lato client.

CORS (condivisione delle risorse multiorigine) è un meccanismo standard che consente le chiamate XHR (XMLHttpRequest) JavaScript eseguite in una pagina web per interagire con le risorse dei domini non originari. CORS è una soluzione comunemente implementata per il criterio same-origin che viene applicato da tutti i browser. Ad esempio, se effettui una chiamata XHR all'API di Twitter dal codice JavaScript in esecuzione nel tuo browser, la chiamata avrà esito negativo. in quanto il dominio che pubblica la pagina nel tuo browser non è uguale al dominio che pubblica l'API Twitter. CORS fornisce una soluzione a questo problema consentendo ai server di attivarla se vogliono fornire la condivisione tra risorse multiorigine.

Per informazioni sull'abilitazione di CORS sui proxy API prima di pubblicare le API, consulta Aggiunta del supporto CORS a un proxy API.

Dimensioni payload messaggio

Per evitare problemi di memoria in Apigee, la dimensione del payload dei messaggi è limitata a 10 MB. Il superamento di queste dimensioni genera un errore protocol.http.TooBigBody.

Questo problema è spiegato anche in Errore durante la richiesta/restituzione di un payload di grandi dimensioni con il proxy Apigee.

Di seguito sono riportate le strategie consigliate per la gestione di messaggi di grandi dimensioni in Apigee:

Invia richieste e risposte in streaming. Tieni presente che, quando trasmetti in streaming, i criteri non hanno più accesso ai contenuti del messaggio. Consulta la sezione Richieste di streaming e risposte.

Guasto

Sfrutta le regole per i problemi per gestire tutta la gestione degli errori. I criteri RaiseFault vengono utilizzati per interrompere il flusso dei messaggi e inviare l'elaborazione al flusso FaultRule.
Nel flusso FaultRule, utilizza un criterio Compiti per creare la risposta agli errori, non un criterio RaiseFault. Eseguire in modo condizionale i criteri AssegnaMessage in base al tipo di errore che si verifica.
Include sempre un gestore predefinito di errori 'catch-all' in modo che gli errori generati dal sistema possano essere mappati a formati di risposta agli errori definiti dal cliente.
Se possibile, assicurati sempre che le risposte di errore corrispondano a tutti i formati standard disponibili nella tua azienda o nel tuo progetto.
Utilizza messaggi di errore significativi e leggibili che suggeriscono una soluzione alla condizione di errore.

Consulta la sezione Gestire gli errori.

Persistenza

Mappe chiave/valore

Utilizza le mappe chiave-valore solo per set di dati limitati. Non sono progettati per essere un datastore a lungo termine.
Tieni presente le prestazioni quando utilizzi le mappe chiave-valore perché queste informazioni vengono archiviate nel database Cassandra.

Consulta il criterio KeyValueMapOperations.

Memorizzazione nella cache delle risposte

Non completare la cache delle risposte se la risposta non ha esito positivo o se la richiesta non è GET. Creazioni, aggiornamenti ed eliminazioni non devono essere memorizzati nella cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
Completa la cache con un singolo tipo di contenuti coerente (ad esempio XML o JSON). Dopo aver recuperato una voce responseCache, convertila nel tipo di contenuto necessario con JSONtoXML o XMLToJSON. Ciò impedirà l'archiviazione di dati doppi, tripli o più.
Assicurati che la chiave cache sia sufficiente per i requisiti di memorizzazione nella cache. In molti casi, request.querystring può essere utilizzato come identificatore univoco.
Non includere la chiave API (client_id) nella chiave cache, a meno che non sia esplicitamente richiesto. Molto spesso, le API protette solo da una chiave restituiscono gli stessi dati a tutti i client di una determinata richiesta. Non è efficiente archiviare lo stesso valore per un numero di voci basate sulla chiave API.
Imposta intervalli di scadenza della cache appropriati per evitare letture sporche.
Se possibile, cerca di eseguire il criterio cache di risposta che completa la cache in corrispondenza del postFlow di risposta ProxyEndpoint il più tardi possibile. In altre parole, fai in modo che venga eseguita dopo la traduzione e i passaggi di mediazione, incluse la mediazione basata su JavaScript e la conversione tra JSON e XML. Memorizzando nella cache i dati con mediazione, evita il costo delle prestazioni di eseguire il passaggio di mediazione ogni volta che recuperi i dati memorizzati nella cache.
Tieni presente che potresti invece memorizzare nella cache i dati non mediati se la mediazione genera una risposta diversa dalla richiesta alla richiesta.
Il criterio cache di risposta per la ricerca della voce cache deve verificarsi nel preflow della richiesta di proxyEndpoint. Evita di implementare una logica eccessiva, ad eccezione della generazione della chiave cache, prima di restituire una voce cache. In caso contrario, i vantaggi della memorizzazione nella cache sono ridotti al minimo.
In generale, dovresti sempre mantenere la ricerca nella cache delle risposte il più vicina possibile alla richiesta del client. Al contrario, dovresti mantenere la popolazione della cache di risposta il più vicino possibile alla risposta del client.
Quando utilizzi più criteri diversi per la cache di risposta in un proxy, segui queste linee guida per garantire un comportamento discreto di ciascuno:
- Esegui ogni criterio in base a condizioni che si escludono a vicenda. In questo modo puoi assicurarti che venga eseguito solo uno di più criteri cache della risposta.
- Definisci risorse diverse per la cache per ogni criterio di risposta della cache. Devi specificare la risorsa cache nell'elemento <CacheResource> del criterio.

Vedi il criterio ResponseCache.

Criterio e codice personalizzato

Criterio o codice personalizzato?

Prima di tutto, utilizza i criteri integrati (ove possibile). I criteri di Apigee sono rafforzati, ottimizzati e supportati. Ad esempio, utilizza i criteri standard AssignMessage e i criteri estrazioneVariables invece di JavaScript (se possibile) per creare payload, estrarre informazioni dai payload (XPath, JSONPath) e così via.
È preferibile usare JavaScript rispetto a Python e Java. Tuttavia, se le prestazioni sono i requisiti primari, Java deve essere utilizzato su JavaScript.

JavaScript

Utilizza JavaScript se è più intuitivo dei criteri Apigee (ad esempio, quando imposti target.url per molte combinazioni URI diverse).
Analisi complesse del payload, come l'iterazione tramite un oggetto JSON e la codifica/decodifica Base64.
Il criterio JavaScript ha un limite di tempo, quindi i cicli illimitati sono bloccati.
Usa sempre i passaggi JavaScript e inserisci i file nella cartella delle risorse di jsc. Il tipo di criterio JavaScript precompila il codice al momento del deployment.

Java

Utilizza Java se le prestazioni sono la priorità più elevata o se la logica non può essere implementata in JavaScript.
Includi i file di origine di Java nel monitoraggio del codice sorgente.

Consulta le norme relative ai callout Java per informazioni sull'utilizzo di Java nei proxy API.

Python

Non utilizzare Python, a meno che non sia assolutamente obbligatorio. Gli script Python possono introdurre colli di bottiglia delle prestazioni per esecuzioni semplici, in quanto vengono interpretati in fase di esecuzione.

Callout script (Java, JavaScript, Python)

Utilizza una procedura di prova globale o equivalente.
Crea eccezioni significative e acquisiscile correttamente per utilizzarle nelle risposte di errore.
Presenta e anticipa le eccezioni. Non utilizzare la prova globale/catch per gestire tutte le eccezioni.
Eseguire controlli non validi o non definiti, se necessario. Un esempio di quando farlo è quando si recuperano variabili di flusso facoltative.
Evita di effettuare richieste HTTP/S all'interno di un callout script. Utilizza invece il criterio callout del servizio poiché il criterio gestisce le connessioni normalmente.

JavaScript

JavaScript sulla piattaforma API supporta XML tramite E4X.

Vedi Modello di oggetti JavaScript.

Java

Quando accedi ai payload dei messaggi, prova a utilizzare context.getMessage() a fronte di context.getResponseMessage o context.getRequestMessage. Ciò garantisce che il codice possa recuperare il payload, sia nei flussi di richiesta che in quelli di risposta.
Importa le librerie nell'organizzazione o nell'ambiente Apigee e non includerle nel file JAR. In questo modo si riducono le dimensioni del bundle e consenti ad altri file JAR di accedere allo stesso repository della libreria.
Importa i file JAR utilizzando l'API delle risorse Apigee anziché includerle nella cartella delle risorse proxy dell'API. Ciò consente di ridurre i tempi di deployment e permette di fare riferimento agli stessi file JAR da più proxy API. Un altro vantaggio è l'isolamento dei caricatori di classe.
Non utilizzare Java per la gestione delle risorse (ad esempio, la creazione e la gestione di pool di thread).

Python

Genera eccezioni significative e recuperale correttamente per l'utilizzo nelle risposte di errore Apigee

Consulta la sezione Criterio PythonScript.

Callout servizio

Esistono molti casi d'uso validi per l'utilizzo del concatenamento di proxy, in cui si utilizza un callout di servizio in un proxy API per chiamare un altro proxy API. Se utilizzi il concatenamento del proxy, assicurati di evitare i callout illimitati nello stesso proxy dell'API.
Se stai connettendo tra proxy che si trovano nella stessa organizzazione e nello stesso ambiente, assicurati di consultare l'articolo Chaining proxy API per ulteriori informazioni sull'implementazione di una connessione locale che evita un overhead di rete non necessario.
Crea un messaggio di richiesta callout per i servizi utilizzando il criterio AssegnaMessage e compila l'oggetto di richiesta in una variabile del messaggio. Ciò include l'impostazione del payload, del percorso e del metodo della richiesta.
L'URL configurato all'interno del criterio richiede la specifica del protocollo, ovvero la parte del protocollo dell'URL, ad esempio https://, non può essere specificata da una variabile. Inoltre, devi utilizzare variabili separate per la parte dell'URL relativa al dominio e per il resto dell'URL. Ad esempio: https://example.com.
Archivia l'oggetto di risposta per un callout del servizio in una variabile messaggio separata. Puoi quindi analizzare la variabile del messaggio e mantenere intatto il payload del messaggio originale per l'utilizzo da parte di altri criteri.

Consulta le norme relative ai callout di servizio.

Accesso alle entità

Criterio AccessEntity

Per migliorare le prestazioni, cerca le app in base a uuid anziché in base al nome.

Vedi il criterio AccessEntity.

Logging

Utilizza un criterio syslog comune tra i bundle e all'interno dello stesso bundle. Questo manterrà un formato di logging coerente.

Vedi il criterio MessageLogging.

Monitoring

I clienti Cloud non sono tenuti a controllare i singoli componenti di Apigee (router, processori di messaggi e così via). Il team Global Operations di Apigee monitora accuratamente tutti i componenti, insieme ai controlli di integrità dell'API, a seconda delle richieste del controllo di integrità da parte del cliente.

Apigee Analytics

Analytics può fornire un monitoraggio non critico dell'API perché vengono misurate le percentuali di errore.

Consulta le dashboard di Analytics.

Debugger

Lo strumento di traccia nell'interfaccia utente di Apigee è utile per eseguire il debug dei problemi dell'API di runtime, durante lo sviluppo o l'operazione di produzione di un'API.

Consulta l'articolo Utilizzare lo strumento di debug.

Sicurezza

Utilizza i criteri di limitazione degli indirizzi IP per limitare l'accesso all'ambiente di test. Consenti l'accesso agli indirizzi IP delle macchine o degli ambienti di sviluppo e non consentire tutte le altre. Vedi il criterio AccessControl.
Applica sempre i criteri di protezione dei contenuti (JSON e o XML) ai proxy API di cui viene eseguito il deployment in produzione. Vedi il criterio JSONThreatProtect.
Leggi i seguenti argomenti per ulteriori best practice sulla sicurezza:

Logica personalizzata nei proxy API

Un requisito comune nella creazione di Proxy dell'API è includere alcune logiche per l'elaborazione di richieste e/o risposte. Anche se molti requisiti possono essere soddisfatti da un insieme predefinito di passaggi/azioni/criteri come la verifica di un token o l'applicazione di una quota o la risposta con un oggetto memorizzato nella cache, spesso è possibile che sia necessario accedere alla programmabilità. Ad esempio, la ricerca di una località (endpoint) da una tabella di routing in base a una chiave trovata in una richiesta e l'applicazione dinamica di un endpoint di destinazione o di un metodo di autenticazione personalizzato/propriatico e così via.

Apigee offre a uno sviluppatore più opzioni per gestire tale logica personalizzata. In questo documento vengono illustrate queste opzioni e viene indicato quando:

Criterio	Casi d'uso dei criteri
JavaScript e PythonScript	Quando utilizzarli: Le funzionalità JavaScript e PythonScript sono equivalenti. La familiarità di uno sviluppatore in una lingua è in genere la motivazione che dipende dall'altra. I criteri JavaScript e PythonScript sono più adatti per l'elaborazione di logiche incorporate in linea che non sono eccessivamente complesse e non richiedono l'utilizzo di librerie di terze parti. Queste norme non hanno lo stesso rendimento delle norme per i callout Java. Quando non utilizzarli: Il gateway API Apigee non è un server di applicazioni (né fornisce il runtime JavaScript completo come `node.js`). Se il callout richiede sempre più di un secondo per essere elaborato, è molto probabile che la logica non appartenga al gateway e dovrebbe fare parte del servizio sottostante. Best practice: Apigee consiglia JavaScript anziché PythonScript, poiché JavaScript offre prestazioni migliori.
JavaCallout	Quando utilizzarli: Le prestazioni dell'elaborazione della logica in linea sono fondamentali. Le librerie Java esistenti forniscono gran parte della logica. Quando non utilizzarli: Il gateway API Apigee non è un server di applicazioni e non è pensato per caricare framework come Spring, JEE e così via. Se il callout in genere richiede più di un secondo per essere elaborato, la logica può essere considerata funzionale (logica di business). Considera l'esternalizzazione come servizio. Per proteggere il gateway dell'API Apigee da comportamenti illeciti, sono previste limitazioni per il tipo di codice che può essere eseguito. Ad esempio, il codice Java che tenta di accedere a determinate librerie di crittografia o di accedere al file system viene bloccato dall'esecuzione. Le applicazioni Java, in particolare quelle che si basano su librerie di terze parti, possono includere molti (e grandi) file JAR. Questo può rallentare il tempo di avvio dei gateway.
ExternalCallout	Quando utilizzarli: Ideale per esternalizzare la logica personalizzata e consentire alla logica personalizzata di accedere al contesto del messaggio e, se necessario, di modificarlo. I callout esterni implementano gRPC e possono avere prestazioni migliori rispetto a un callout servizio. Quando utilizzi Apigee X o Apigee ibrido su Google Cloud, considera l'utilizzo di Cloud Functions o Cloud Run per ospitare tale logica. In sostituzione della funzionalità Target ospitati in Apigee Edge. Quando non utilizzi: Per una logica leggera che può essere eseguita rapidamente, in linea.
ServiceCallout	Quando utilizzarli: La migliore logica è implementata al di fuori del gateway. Questa logica può avere un proprio ciclo di vita (release e controllo delle versioni) e non influisce sul funzionamento del gateway. Quando l'endpoint REST/SOAP/GraphQL esiste già o può essere facilmente implementato Quando utilizzi Apigee X o Apigee ibrido su Google Cloud, valuta l'utilizzo di Cloud Functions o Cloud Run per ospitare tale logica. In sostituzione della funzionalità Target ospitati in Apigee Edge. Quando non utilizzi: Per una logica leggera che può essere eseguita rapidamente, in linea Il proxy API deve trasferire il contesto (come le variabili) o ricevere contesto dall'implementazione esterna

In sintesi:

Se la logica è semplice o banale, utilizza JavaScript (preferibilmente) o PythonScript.
Se la logica in linea richiede prestazioni migliori rispetto a JavaScript o PythonScript, utilizza JavaCallout.
Se la logica deve essere esternalizzata, utilizza callout esterno.
Se hai già implementazioni esterne e/o gli sviluppatori hanno familiarità con REST, utilizza ServiceCallout.

La figura seguente illustra questo processo: