Best practice per la progettazione e lo sviluppo di proxy API

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

Lo scopo di questo documento è fornire una serie di standard e best practice per lo sviluppo con Apigee Edge. Gli argomenti trattati includono progettazione, codifica, 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 documento è in continuo aggiornamento e verrà aggiornato di volta in volta.

Oltre alle linee guida riportate qui, potrebbe esserti utile anche il post della community sugli antipattern di Apigee Edge.

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 dei criteri non sono sufficientemente descrittivi per esprimere la funzionalità di base del flusso.
  • Rendi utili i commenti. Evita commenti scontati.
  • Utilizza rientri, spaziature, 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 negli ambienti di sviluppo locale. Ad esempio, per riutilizzare un criterio, memorizzalo nel controllo del codice sorgente in modo che gli sviluppatori possano sincronizzarsi e utilizzarlo nei propri ambienti di sviluppo proxy.

  • Per attivare il DRY ("don't repeat yourself"), ove possibile, le configurazioni dei criteri e gli script devono implementare funzioni specializzate e riutilizzabili. Ad esempio, un criterio dedicato per estrarre i parametri di query dai messaggi di richiesta potrebbe essere chiamato ExtractVariables.ExtractRequestParameters. Un criterio dedicato per iniettare le intestazioni CORS potrebbe essere chiamato AssignMessage.SetCORSHeaders. Questi criteri possono quindi essere memorizzati nel sistema di controllo del codice sorgente e aggiunti a ogni proxy API che deve estrarre i parametri o impostare le intestazioni CORS, senza che sia necessario creare configurazioni ridondanti (e quindi meno gestibili).
  • Elimina i criteri e le risorse inutilizzati (JavaScript, Java, XSLT e così via) dai proxy API, soprattutto le risorse di grandi dimensioni che potrebbero rallentare le procedure di importazione e deployment.

Convenzioni di denominazione

  • L'attributo criterio name e il nome del file del criterio XML devono essere identici.
  • L'attributo name del criterio Script e ServiceCallout e il nome del file della risorsa devono essere identici.
  • DisplayName deve descrivere con precisione la funzione del criterio a chi non ha mai utilizzato il 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 criteri. Ad esempio, utilizza prefissi brevi seguiti da una sequenza di parole descrittive separate da trattini. Ad esempio, AM-xxx per i criteri AssignMessage. 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, ad esempio camelCase o under_score, utilizzalo nell'intero proxy API.
  • Se possibile, utilizza i prefissi delle variabili per organizzare le variabili in base alla loro finalità, ad esempio Consumer.username e Consumer.password.

Sviluppo di proxy API

Considerazioni iniziali sul design

  • Per indicazioni sulla progettazione di 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 codificare tutta la logica del proxy nelle risorse JavaScript, Java o Python.
  • Costruisci i flussi in modo organizzato. È preferibile utilizzare più flussi, ciascuno con una singola condizione, anziché più allegati condizionali allo stesso PreFlow e Postflow.
  • Come "piano di riserva", crea un proxy API predefinito con un BasePath di ProxyEndpoint di /. Può essere utilizzato 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 al valore predefinito messaging.adaptors.http.flow.ApplicationNotFound.
  • Utilizza le risorse TargetServer per disaccoppiare le configurazioni di TargetEndpoint dagli URL specifici, supportando la promozione tra gli ambienti.
    Consulta Bilanciamento del carico tra server di backend.
  • Se hai più RouteRule, creane una come "predefinita", ovvero come RouteRule senza condizioni. Assicurati che la regola di routing predefinita sia definita per ultima nell'elenco dei percorsi condizionali. Le regole Route vengono valutate dall'alto verso il basso in ProxyEndpoint.
    Consulta il riferimento per la configurazione dei proxy API.
  • Dimensioni del bundle proxy API: i bundle proxy API non possono avere dimensioni maggiori di 15 MB. In Apigee Edge for Private Cloud, puoi modificare il limite di dimensioni modificando la proprietà thrift_framed_transport_size_in_mb nelle seguenti posizioni: cassandra.yaml (in Cassandra) e conf/apigee/management-server/repository.properties.
  • Versionamento delle API: per le opinioni e i consigli di Apigee sul versionamento delle API, consulta la sezione Versionamento nell'ebook Web API Design: The Missing Link.

Attivazione di CORS

Prima di pubblicare le API, devi attivare il CORS sui proxy API per supportare le richieste cross-origin lato client.

CORS (Cross-Origin Resource Sharing) è un meccanismo standard che consente alle chiamate XMLHttpRequest (XHR) di JavaScript eseguite in una pagina web di interagire con le risorse di domini diversi da quello di origine. CORS è una soluzione comunemente implementata per i criteri della stessa origine che viene applicata da tutti i browser. Ad esempio, se effettui una chiamata XHR all'API Twitter dal codice JavaScript eseguito nel browser, la chiamata non andrà a buon fine. Questo perché il dominio che pubblica la pagina nel browser non è lo stesso del dominio che pubblica l'API Twitter. CORS fornisce una soluzione a questo problema consentendo ai server di "attivare" la condivisione delle risorse tra origini se vogliono fornire questa funzionalità.

Per informazioni su come attivare CORS sui proxy API prima di pubblicare le API, consulta Aggiunta del supporto CORS a un proxy API.

Dimensioni del payload del messaggio

Per evitare problemi di memoria in Edge, le dimensioni del payload del messaggio sono limitate a 10 MB. Se si superano queste dimensioni, viene generato un errore protocol.http.TooBigBody.

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

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

  • Stream di richieste e risposte. Tieni presente che, quando trasmetti in streaming, le norme non hanno più accesso ai contenuti dei messaggi. Consulta Richieste e risposte con flussi di dati.
  • In Edge for Private Cloud versione 4.15.07 e precedenti, modifica il file dell'elaboratore dei messaggi http.properties per aumentare il limite nel parametro HTTPResponse.body.buffer.limit. Assicurati di eseguire il test prima di eseguire il deployment della modifica in produzione.
  • In Edge for Private Cloud versione 4.16.01 e successive, le richieste con un payload devono includere l'intestazione Content-Length o, in caso di streaming, l'intestazione "Transfer-Encoding: chunked". Per una richiesta POST a un proxy API con un payload vuoto, devi passare un valore Content-Length pari a 0.
  • In Edge for Private Cloud 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 di dimensioni dei messaggi sul router o sul Message Processor.

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

Gestione degli errori

  • Utilizza FaultRules per gestire tutta la gestione degli errori. I criteri RaiseFault vengono utilizzati per interrompere il flusso di messaggi e inviare l'elaborazione al flusso FaultRules.
  • All'interno del flusso FaultRules, utilizza i criteri AssignMessage per creare la risposta all'errore, non i criteri RaiseFault. Esegui i criteri AssignMessage in modo condizionale in base al tipo di errore che si verifica.
  • Include sempre un gestore degli errori "generico" predefinito in modo che gli errori generati dal sistema possano essere mappati ai formati di risposta agli errori definiti dal cliente.
  • Se possibile, assicurati sempre che le risposte agli errori corrispondano a qualsiasi formato standard disponibile nella tua azienda o nel tuo progetto.
  • Utilizza messaggi di errore significativi e leggibili che suggeriscano una soluzione alla condizione di errore.

Consulta la sezione Gestione degli errori.

Per le best practice del settore, consulta la sezione Design della risposta di errore RESTful.

Persistenza

Mappe chiave/valore

  • Utilizza le mappe chiave/valore solo per set di dati limitati. Non sono progettati per essere un archivio di dati a lungo termine.
  • Tieni conto del rendimento quando utilizzi le mappe chiave/valore, poiché queste informazioni vengono memorizzate nel database Cassandra.

Consulta le norme relative alle operazioni mappa chiave-valore.

Memorizzazione nella cache delle risposte

  • Non compilare la cache della risposta se la risposta non è corretta o se la richiesta non è GET. Le operazioni di creazione, aggiornamento ed eliminazione non devono essere memorizzate nella cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Compila la cache con un unico 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 di memorizzare dati doppi, tripli o più.
  • Assicurati che la chiave della cache sia sufficiente per soddisfare il requisito di memorizzazione nella cache. In molti casi, il valore request.querystring può essere utilizzato come identificatore univoco.
  • Non includere la chiave API (client_id) nella chiave cache, a meno che non sia obbligatoria. Molto spesso, le API protette solo da una chiave restituiscono gli stessi dati a tutti i client per una determinata richiesta. Non è efficiente memorizzare lo stesso valore per un numero di voci in base alla chiave API.
  • Imposta intervalli di scadenza della cache appropriati per evitare letture sporche.
  • Se possibile, cerca di eseguire il criterio di cache delle risposte che compila la cache nel post-flusso della risposta ProxyEndpoint il più tardi possibile. In altre parole, eseguila dopo i passaggi di traduzione e mediazione, inclusa la mediazione basata su JavaScript e la conversione tra JSON e XML. Memorizzando nella cache i dati mediati, eviti il costo in termini di prestazioni dell'esecuzione del passaggio di mediazione ogni volta che recuperi i dati memorizzati nella cache.

    Tieni presente che potresti preferire memorizzare nella cache i dati non mediati se la mediazione genera una risposta diversa da una richiesta all'altra.

  • Il criterio della cache della risposta per cercare la voce della cache deve verificarsi nel PreFlow della richiesta ProxyEndpoint. Evita di implementare troppa logica, oltre alla generazione della chiave della cache, prima di restituire una voce della cache. In caso contrario, i vantaggi della memorizzazione nella cache vengono ridotti al minimo.
  • In generale, devi sempre mantenere la ricerca nella cache della risposta il più vicino possibile alla richiesta del client. Al contrario, devi mantenere la popolazione della cache delle risposte il più vicino possibile alla risposta del cliente.
  • Quando utilizzi più criteri di cache delle risposte diversi in un proxy, segui queste linee guida per garantire un comportamento distinto per ciascuno:
    • Esegui ogni criterio in base a condizioni mutuamente esclusive. In questo modo, verrà eseguito solo uno dei più criteri di cache delle risposte.
    • Definisci risorse della cache diverse per ogni criterio della cache delle risposte. Specifica la risorsa della cache nell'elemento <CacheResource> del criterio.

Consulta le norme relative alla cache delle risposte.

Norme e codice personalizzato

Criteri o codice personalizzato?

  • Utilizza innanzitutto i criteri integrati (se possibile). I criteri Apigee sono rafforzati, ottimizzati e supportati. Ad esempio, utilizza le norme standard AssignMessage ed ExtractVariables anziché JavaScript (se possibile) per creare payload, estrarre informazioni dai payload (XPath, JSONPath) e così via.
  • È preferibile utilizzare JavaScript rispetto a Python e Java. Tuttavia, se il rendimento è il requisito principale, è preferibile utilizzare Java anziché JavaScript.

JavaScript

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

Consulta Programmare i proxy API con JavaScript.

Java

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

Per informazioni sull'utilizzo di Java nei proxy API, consulta Convertire la risposta in lettere maiuscole con un callout Java e Norme relative ai callout Java.

Python

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

Callout di script (Java, JavaScript, Python)

  • Utilizza un blocco try/catch globale o equivalente.
  • Lanciati eccezioni significative e gestiscile correttamente per utilizzarle nelle risposte agli errori.
  • Lancia ed esegui il rilevamento delle eccezioni in anticipo. Non utilizzare try/catch globale per gestire tutte le eccezioni.
  • Esegui controlli su valori null e non definiti, se necessario. Un esempio di quando eseguire questa operazione è quando recupero le variabili di flusso facoltative.
  • Evita di effettuare richieste HTTP/S all'interno di un callout di script. Utilizza invece il criterio Apigee ServiceCallout, in quanto gestisce le connessioni in modo corretto.

JavaScript

  • JavaScript sulla piattaforma API supporta XML tramite E4X.

Consulta Modello oggetto JavaScript.

Java

  • Quando accedi ai payload dei messaggi, prova a utilizzare context.getMessage() anziché context.getResponseMessage o context.getRequestMessage. In questo modo, il codice può recuperare il payload sia nei flussi di richiesta che di risposta.
  • Importa le librerie nell'organizzazione o nell'ambiente Apigee Edge e non includerle nel file JAR. In questo modo si riducono le dimensioni del bundle e altri file JAR potranno accedere allo stesso repository della biblioteca.
  • Importa i file JAR utilizzando l'API Apigee Resources anziché includerli all'interno della cartella delle risorse proxy dell'API. In questo modo, i tempi di implementazione verranno ridotti e sarà possibile fare riferimento agli stessi file JAR da più proxy API. Un altro vantaggio è l'isolamento del caricatore di classi.
  • Non utilizzare Java per la gestione delle risorse (ad esempio, la creazione e la gestione di pool di thread).

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

Python

  • Lanciati eccezioni significative e gestiscile correttamente per utilizzarle nelle risposte agli errori di Apigee

Consulta le norme relative agli script Python.

ServiceCallouts

  • Esistono molti casi d'uso validi per l'utilizzo della catena di proxy, in cui utilizzi un callout di servizio in un proxy API per chiamare un altro proxy API. Se utilizzi il concatenamento di proxy, assicurati di evitare callout ricorsivi con "loop infinito" nello stesso proxy API.

    Se ti colleghi tra proxy che si trovano nella stessa organizzazione e nello stesso ambiente, consulta la sezione Collegare in serie i proxy API per saperne di più sull'implementazione di una connessione locale che eviti un aggravio della rete non necessario.

  • Crea un messaggio di richiesta ServiceCallout utilizzando il criterio AssignMessage e compila l'oggetto request in una variabile di messaggio. (Sono inclusi l'impostazione del payload, del percorso e del metodo della richiesta).
  • L'URL configurato all'interno del criterio richiede la specifica del protocollo, il che significa che la parte di protocollo dell'URL, ad esempio https://, non può essere specificata da una variabile. Inoltre, devi utilizzare variabili separate per la parte di dominio dell'URL e per il resto dell'URL. Ad esempio: https://{domain}/{path}
  • Memorizza l'oggetto di risposta per un ServiceCallout in una variabile di messaggio separata. Puoi quindi analizzare la variabile messaggio e mantenere inalterato il payload del messaggio originale per l'utilizzo da parte di altri criteri.

Consulta le norme relative alle chiamate di servizio.

Accesso alle entità

Criterio AccessEntity

  • Per un rendimento migliore, cerca le app per uuid anziché per nome.

Consulta le norme relative alle persone giuridiche di accesso.

Logging

  • Utilizza un criterio syslog comune in tutti i bundle e nello stesso bundle. In questo modo, manterrai un formato di registrazione coerente.

Consulta le norme relative a LogMessaggi.

Monitoraggio

I clienti cloud non sono tenuti a controllare i singoli componenti di Apigee Edge (router, elaboratori di messaggi e così via). Il team Global Operations di Apigee monitora attentamente tutti i componenti, nonché i controlli di integrità delle API, in base alle richieste del cliente.

Apigee Analytics

Analytics può fornire il monitoraggio delle API non critiche poiché vengono misurate le percentuali di errore.

Consulta le dashboard di Analytics.

Trace

Lo strumento di traccia nell'interfaccia utente di gestione di API Edge è utile per eseguire il debug dei problemi relativi alle API di runtime durante lo sviluppo o il funzionamento in produzione di un'API.

Vedi Utilizzare lo strumento Traccia.

Sicurezza