Best practice per la progettazione e lo sviluppo di proxy API

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

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

Oltre alle linee guida qui riportate, potresti trovare utile anche il post della community Apigee Edge Antipatterns.

Standard di sviluppo

Commenti e documentazione

  • Fornisci commenti in linea nelle configurazioni ProxyEndpoint e TargetEndpoint. I commenti migliorano la leggibilità di un flusso, soprattutto dove i nomi dei file dei criteri non sono sufficientemente descrittivi per esprimere la funzionalità di base del flusso.
  • Rendi utili i commenti. Evita i commenti ovvi.
  • Usa rientro, spaziatura, allineamento verticale e così via coerenti.

Codifica in stile framework

La codifica in stile framework prevede l'archiviazione delle risorse proxy API nel tuo sistema di controllo della versione per il riutilizzo in ambienti di sviluppo locali. Ad esempio, per riutilizzare un criterio, archivialo nel controllo del codice sorgente, in modo che gli sviluppatori possano sincronizzarlo con il criterio e utilizzarlo nei loro ambienti di sviluppo proxy.

  • Per attivare la modalità DRY ("non ripetere tutto") ove possibile, le configurazioni dei criteri e gli script devono implementare funzioni specializzate riutilizzabili. Ad esempio, un criterio dedicato per estrarre i parametri di ricerca dai messaggi di richiesta potrebbe essere chiamato ExtractVariables.ExtractRequestParameters. Un criterio dedicato per inserire le intestazioni CORS potrebbe essere chiamato AssignMessage.SetCORSHeaders. Questi criteri potrebbero quindi essere archiviati nel sistema di controllo del codice sorgente e aggiunti a ogni proxy API che deve estrarre parametri o impostare intestazioni CORS, senza che tu debba creare configurazioni ridondanti (e quindi meno gestibili).
  • Elimina i criteri e le risorse inutilizzate (JavaScript, Java, NoSQL e così via) 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 del criterio Script e ServiceCallout name e il nome del file di risorse devono essere identici.
  • DisplayName deve descrivere con precisione la funzione delle norme a qualcuno che non ha mai lavorato con il proxy API in questione.
  • Assegna i nomi ai criteri in base alla loro funzione. Apigee consiglia di stabilire una convenzione di denominazione coerente per i criteri. Ad esempio, utilizza prefissi brevi seguiti da una sequenza di parole descrittive separate da trattini. Ad esempio, AM-xxx per i criteri di AttributionMessage. Vedi anche lo strumento Apigeelint.
  • Utilizza le estensioni appropriate per i file di risorse, .js per JavaScript, .py per Python e .jar per i file JAR Java.
  • I nomi delle variabili devono essere coerenti. Se scegli uno stile, come camelCase o trattino basso, utilizzalo tramite il proxy API.
  • Se possibile, utilizza i prefissi delle variabili per organizzare le variabili in base al loro scopo, ad esempio Consumer.username e Consumer.password.

Sviluppo di proxy API

Considerazioni iniziali sul design

  • Per indicazioni sulla progettazione delle API RESTful, scarica l'ebook Web API Design: The Missing Link.
  • Sfrutta i criteri e le funzionalità di Apigee Edge ove possibile per creare proxy API. Evita di programmare tutte le logiche proxy nelle risorse JavaScript, Java o Python.
  • Costruire i flussi in modo organizzato. Sono preferibili più flussi, ciascuno con una singola condizione, a più collegamenti condizionali agli stessi flussi di pre-flusso e post-flusso.
  • Come "failsafe", crea un proxy API predefinito con un BasePath di ProxyEndpoint di /. Può essere utilizzata per reindirizzare le richieste dell'API di base a un sito per sviluppatori, per restituire una risposta personalizzata o per eseguire un'altra azione più utile rispetto alla restituzione dell'elemento messaging.adaptors.http.flow.ApplicationNotFound predefinito.
  • Utilizza le risorse TargetServer per disaccoppiare le configurazioni TargetEndpoint dagli URL concreti, supportando la promozione in più ambienti.
    Vedi Bilanciamento del carico tra server di backend.
  • Se disponi di più RouteRules, creane una come "default", ovvero come una RouteRule senza condizione. Assicurati che la RouteRule predefinita sia definita per ultima nell'elenco delle route condizionali. RouteRules viene valutata dall'alto verso il basso in ProxyEndpoint.
    Consulta il riferimento per la configurazione del proxy API.
  • Dimensioni bundle proxy API: i pacchetti di proxy API non possono superare i 15 MB. In Apigee Edge per il cloud privato, puoi modificare il limite delle dimensioni modificando la proprietà thrift_framed_transport_size_in_mb nelle seguenti posizioni: cassandra.yaml (in Cassandra) e conf/apigee/management-server/repository.properties.
  • Controllo delle versioni delle API: per le opinioni e i suggerimenti di Apigee sul controllo delle versioni delle API, consulta la sezione relativa al controllo delle versioni nell'ebook Web API Design: The Missing Link.

Abilitazione di CORS

Prima di pubblicare le API, devi attivare CORS sui proxy API per supportare le richieste multiorigine lato client.

CORS (Cross-Origin Resource Sharing) è un meccanismo standard che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con le risorse dei domini non origini. CORS è una soluzione comunemente implementata per il criterio della stessa origine applicato da tutti i browser. Ad esempio, se effettui una chiamata XHR all'API Twitter dal codice JavaScript in esecuzione nel browser, la chiamata avrà esito negativo. Questo perché il dominio che pubblica la pagina nel tuo browser non è lo stesso che fornisce l'API Twitter. CORS offre una soluzione a questo problema consentendo ai server di eseguire l'attivazione se vogliono fornire la condivisione delle risorse tra origini.

Per informazioni sull'abilitazione di CORS sui proxy API prima di pubblicare le API, consulta la pagina relativa all'aggiunta del supporto CORS a un proxy API.

Dimensioni payload messaggio

Per evitare problemi di memoria in Edge, le dimensioni del payload dei messaggi sono limitate a 10 MB. Se superi queste dimensioni, viene visualizzato un errore protocol.http.TooBigBody.

Questo problema viene discusso anche in questo post della community di Apigee.

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

  • Trasmetti richieste e risposte. Tieni presente che quando trasmetti in streaming, i criteri non hanno più accesso ai contenuti dei messaggi. Vedi Richieste e risposte di flussi di dati.
  • In Edge per Cloud privato versione 4.15.07 e precedenti, modifica il file http.properties del processore di messaggi per aumentare il limite nel parametro HTTPResponse.body.buffer.limit. Assicurati di eseguire i test prima di eseguire il deployment della modifica in produzione.
  • In Edge per Private Cloud versione 4.16.01 e successive, le richieste con un payload devono includere l'intestazione Content-Length o, in caso di trasmissione in modalità flusso, l'intestazione "Transfer-Encoding: chunked". Per eseguire una POST su un proxy API con un payload vuoto, devi passare un valore Content-Length pari a 0.
  • In Edge per cloud privato versione 4.16.01 e successive, imposta le seguenti proprietà in /opt/apigee/router.properties o message-processor.properties per modificare i limiti. Per saperne di più, consulta Impostare il limite per le dimensioni dei messaggi sul router o sul processore di messaggi.

    Entrambe le proprietà hanno un valore predefinito di "10m" che corrisponde a 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Gestione dei guasti

  • Utilizzare FaultRules per gestire tutta la gestione dei guasti. I criteri AlzaFault vengono utilizzati per arrestare il flusso di messaggi e inviare l'elaborazione al flusso FaultRules.
  • All'interno del flusso FaultRules, utilizza i criteri AssegnaMessage per creare la risposta all'errore, non i criteri AlzaFault. Esegui in modo condizionale i criteri di AssegnaMessage in base al tipo di errore che si verifica.
  • Include sempre un gestore di errori "catch-all" predefinito in modo che gli errori generati dal sistema possano essere mappati a formati di risposta agli errori definiti dal cliente.
  • Se possibile, fai sempre in modo che le risposte di errore corrispondano a qualsiasi formato standard disponibile 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 Gestione degli errori.

Per le best practice del settore, consulta la pagina relativa alla progettazione delle risposte agli errori RESTful.

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.
  • Considera le prestazioni quando utilizzi mappe chiave/valore, poiché queste informazioni vengono archiviate nel database Cassandra.

Consulta le norme relative alle operazioni di mappatura delle coppie chiave-valore.

Memorizzazione nella cache delle risposte

  • Non compilare la cache delle risposte se la risposta non ha esito positivo o se la richiesta non è una richiesta GET. Le creazioni, gli aggiornamenti e le eliminazioni non devono essere memorizzati nella cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Compila 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. In questo modo eviterai l'archiviazione di dati doppi, tripli o aggiuntivi.
  • Assicurati che la chiave cache sia sufficiente per soddisfare il requisito 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 per una determinata richiesta. Archiviare lo stesso valore per un numero di voci in base alla chiave API non è efficace.
  • Imposta intervalli di scadenza della cache appropriati per evitare letture errate.
  • Quando possibile, cerca di eseguire il criterio della cache delle risposte che compila la cache al PostFlow di risposta ProxyEndpoint il più tardi possibile. In altre parole, fai in modo che venga eseguito dopo i passaggi di traduzione e mediazione, tra cui la mediazione basata su JavaScript e la conversione tra JSON e XML. Mediante la memorizzazione nella cache dei dati con mediazione, eviti i costi legati alle prestazioni dell'esecuzione del passaggio di mediazione ogni volta che recuperi i dati memorizzati nella cache.

    Tieni presente che ti conviene memorizzare nella cache i dati non mediati se la mediazione genera una risposta diversa da quella richiesta a richiesta.

  • Il criterio della cache delle risposte per cercare la voce della cache deve essere applicato nel preflusso della richiesta ProxyEndpoint. Evita di implementare troppa logica, diversa dalla generazione di chiavi cache, prima di restituire una voce di cache. In caso contrario, i vantaggi della memorizzazione nella cache sono ridotti al minimo.
  • In generale, devi sempre mantenere la ricerca della cache delle risposte il più vicino possibile alla richiesta del client. Al contrario, devi mantenere la compilazione della cache delle risposte il più vicino possibile alla risposta del client.
  • Quando utilizzi più criteri di cache delle risposte diversi in un proxy, segui queste linee guida per garantire un comportamento discreto per ciascuno:
    • Esegui ciascun criterio in base a condizioni che si escludono a vicenda. Ciò garantisce che venga eseguito solo uno dei vari criteri della cache di risposta.
    • Definisci le risorse della cache diverse per ciascun criterio della cache delle risposte. Puoi specificare la risorsa cache nell'elemento <CacheResource> del criterio.

Consulta i criteri relativi alla cache delle risposte.

Criterio e codice personalizzato

Norma o codice personalizzato?

  • Usa prima di tutto i criteri integrati (se possibile). I criteri di Apigee sono protetti, ottimizzati e supportati. Ad esempio, se possibile, utilizza i criteri standard AssegnaMessage ed ExtractVariables invece di JavaScript per creare payload, estrarre informazioni dai payload (XPath, JSONPath) e così via.
  • È preferibile JavaScript rispetto a Python e Java. Tuttavia, se le prestazioni sono il requisito principale, è consigliabile utilizzare Java anziché JavaScript.

JavaScript

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

Consulta Programmazione dei proxy API con JavaScript.

Java

  • Utilizza Java se hai la massima priorità per le prestazioni o se la logica non può essere implementata in JavaScript.
  • Includi i file di origine Java nel monitoraggio del codice sorgente.

Consulta Convertire la risposta in lettere maiuscole con un callout Java e Criterio per i callout Java per informazioni sull'utilizzo di Java nei proxy API.

Python

  • Non utilizzare Python a meno che non sia assolutamente richiesto. Gli script Python possono introdurre colli di bottiglia delle prestazioni per esecuzioni semplici, poiché vengono interpretati in fase di runtime.

Callout script (Java, JavaScript, Python)

  • Utilizza un processo globale di prova/catch o equivalente.
  • Genera eccezioni significative e individuale correttamente per utilizzarle nelle risposte di errore.
  • Lancia e individua le eccezioni in anticipo. Non utilizzare la funzionalità globale prova/catch per gestire tutte le eccezioni.
  • Se necessario, esegui i controlli nulli e non definiti. Un esempio di quando eseguire questa operazione è il recupero di variabili di flusso facoltative.
  • Evita di effettuare richieste HTTP/S all'interno del callout di uno script. Utilizza invece il criterio Apigee ServiceCallout perché gestisce le connessioni in modo controllato.

JavaScript

  • JavaScript sulla piattaforma API supporta il formato XML tramite E4X.

Consulta Modello a oggetti JavaScript.

Java

  • Quando accedi ai payload dei messaggi, prova a utilizzare context.getMessage() invece di context.getResponseMessage o context.getRequestMessage. Ciò garantisce che il codice possa recuperare il payload, nei flussi di richiesta e risposta.
  • Importa le librerie nell'organizzazione o nell'ambiente Apigee Edge e non includerle nel file JAR. Questo riduce le dimensioni del bundle e consente ad altri file JAR di accedere allo stesso repository di librerie.
  • Importa i file JAR utilizzando l'API Apigee Resources anziché includerli nella cartella delle risorse proxy API. Ciò ridurrà i tempi di deployment e consentirà il riferimento agli stessi file JAR da parte di più proxy API. Un altro vantaggio è l'isolamento del caricatore di classi.
  • Non utilizzare Java per la gestione delle risorse (ad esempio, per creare e gestire i pool di thread).

Vedi Convertire la risposta in lettere maiuscole con un callout Java.

Python

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

Consulta i criteri relativi agli script di Python.

ServiceCallouts

  • 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 di proxy, assicurati di evitare i callout ricorrenti a "ciclo infinito" nello stesso proxy API.

    Se ti connetti tra proxy che si trovano nella stessa organizzazione e nello stesso ambiente, assicurati di consultare l'articolo Utilizzare i proxy dell'API Cisco insieme per ulteriori informazioni sull'implementazione di una connessione locale che eviti un overhead di rete superfluo.

  • Crea un messaggio di richiesta ServiceCallout utilizzando il criterio AssegnaMessage e compila l'oggetto di richiesta in una variabile messaggio. Ciò include l'impostazione di payload, percorso e metodo della richiesta.
  • L'URL configurato all'interno del criterio richiede la specifica di protocollo, il che significa che la parte relativa al protocollo dell'URL, ad esempio https://, non può essere specificata da una variabile. Inoltre, devi utilizzare variabili distinte per la parte del dominio dell'URL e per il resto dell'URL. Ad esempio: https://{domain}/{path}
  • Archivia l'oggetto risposta per un ServiceCallout in una variabile di messaggio separata. Puoi quindi analizzare la variabile del messaggio e mantenere intatto il payload del messaggio originale per poterlo utilizzare con altri criteri.

Consulta le norme sui callout di servizio.

Accedere alle entità

Criterio AccessEntity

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

Vedi Criterio di entità di accesso.

Logging

  • Utilizza un criterio syslog comune in tutti i pacchetti e all'interno dello stesso bundle. In questo modo manterrà un formato di logging coerente.

Vedi Criterio MessageLogging.

Monitoraggio

I clienti Cloud non sono tenuti a controllare i singoli componenti di Apigee Edge (router, processori di messaggi e così via). Il team Global Operations di Apigee sta monitorando attentamente tutti i componenti, insieme ai controlli di integrità delle API, date le richieste di controllo di integrità da parte del cliente.

Analisi Apigee

Analytics può fornire un monitoraggio delle API non critico man mano che vengono misurate le percentuali di errore.

Consulta Dashboard di Analytics.

Traccia

Lo strumento di traccia nell'interfaccia utente di gestione dell'API Edge è utile per il debug dei problemi dell'API di runtime, durante le operazioni di sviluppo o produzione di un'API.

Consulta la sezione Utilizzo dello strumento Trace.

Sicurezza