Crea un proxy API da una specifica OpenAPI

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

Cosa imparerai a fare

In questo tutorial imparerai a:

  • Crea un proxy API Edge da una specifica OpenAPI.
  • Chiama il proxy API utilizzando cURL.
  • Aggiungere un criterio a un flusso condizionale.
  • Testa la chiamata del criterio utilizzando cURL.

In questo tutorial imparerai a creare un proxy API Edge da una specifica OpenAPI utilizzando l'interfaccia utente di gestione di Apigee Edge. Quando chiami il proxy API con un client HTTP, ad esempio cURL, il proxy API invia la richiesta al servizio di destinazione della simulazione Apigee.

Informazioni sull'iniziativa Open API

Apri iniziativa API
"Open API Initiative (OAI) si concentra sulla creazione, l'evoluzione e la promozione di un formato di descrizione API indipendente dal fornitore e basato sulla specifica Swagger." Per ulteriori informazioni sull'Open API Initiative, visita il sito https://openapis.org.

Una specifica OpenAPI utilizza un formato standard per descrivere un'API RESTful. Scritta in formato JSON o YAML, una specifica OpenAPI è leggibile dalla macchina, ma è anche facile da leggere e capire per le persone. La specifica descrive questi elementi di un'API come percorso di base, percorsi e verbi, intestazioni, parametri di query, operazioni, tipi di contenuti, descrizioni delle risposte e altro ancora. Inoltre, una specifica OpenAPI viene comunemente utilizzata per generare la documentazione dell'API.

Informazioni sul servizio target di simulazione Apigee

Il servizio di destinazione fittizio Apigee utilizzato in questo tutorial è ospitato su Apigee e restituisce dati semplici. Non richiede chiavi API o token di accesso. Infatti, puoi accedervi da un browser web. Fai clic di seguito per fare una prova:

http://mocktarget.apigee.net

Il servizio di destinazione restituisce il saluto Hello, guest!

Per informazioni sul set completo di API supportate dal servizio di destinazione fittizio, fai clic su quanto segue:

http://mocktarget.apigee.net/help

Che cosa ti serve

  • Un account Apigee Edge. Se non hai un account, puoi registrarti seguendo le istruzioni nella sezione Creazione di un account Apigee Edge.
  • Una specifica OpenAPI. In questo tutorial utilizzerai la specifica OpenAPI mocktarget.yaml, che descrive il servizio di destinazione fittizio di Apigee, http://mocktarget.apigee.net. Per maggiori informazioni, vedi https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
  • cURL installato sulla tua macchina per effettuare chiamate API dalla riga di comando o da un browser web.

Crea il proxy API

Perimetrale

Per creare il proxy API da una specifica OpenAPI utilizzando l'interfaccia utente Edge:

  1. Accedi ad https://apigee.com/edge.
  2. Fai clic su Proxy API nella finestra principale.

    In alternativa, puoi selezionare Sviluppo > Proxy API nella barra di navigazione a sinistra.

    Fai clic su Proxy API nella pagina di destinazione

  3. Fai clic su + Proxy.
    Aggiungi proxy API
  4. Nella procedura guidata Crea proxy, fai clic su Utilizza specifiche OpenAPI per il modello proxy inverso (più comune).
    Crea un tipo di proxy
  5. Fai clic su Importa da URL e inserisci le seguenti informazioni:
    • OpenAPI Spec URL: percorso dei contenuti non elaborati su GitHub per la specifica OpenAPI nel campo URL:
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • Nome specifica: nome della specifica OpenAPI, ad esempio Target fittizio.

      Questo nome viene utilizzato per archiviare la specifica OpenAPI nell'archivio delle specifiche. Vedi Gestire le specifiche.

  6. Fai clic su Importa.

    Viene visualizzata la pagina Dettagli nella procedura guidata Crea proxy. I campi vengono precompilati utilizzando i valori definiti nella specifica OpenAPI, come mostrato di seguito

    La seguente tabella descrive i valori predefiniti precompilati utilizzando le proprietà nella specifica OpenAPI. Di seguito la tabella è mostrato un estratto della specifica OpenAPI che illustra le proprietà utilizzate.

    Campo Descrizione Predefinito
    Nome Nome del proxy API. Ad esempio: Mock-Target-API. Proprietà title della specifica OpenAPI con spazi sostituiti da trattini
    Percorso base Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione. L'URL visibile al pubblico di questo proxy API è composto dal nome della tua organizzazione, da un ambiente in cui è stato eseguito il deployment del proxy API e da questo percorso di base. Ad esempio: http://myorg-test.apigee.net/mock-target-api Contenuti del campo Nome convertiti in lettere minuscole
    Descrizione Descrizione del proxy API. description dalla specifica OpenAPI
    Target (API esistente) URL di destinazione richiamato per conto di questo proxy API. È possibile utilizzare qualsiasi URL accessibile tramite internet aperto. Ad esempio: http://mocktarget.apigee.net servers dalla specifica OpenAPI

    Di seguito è riportato un estratto della specifica OpenAPI che mostra le proprietà utilizzate per precompilare i campi.

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  7. Modifica il campo Descrizione come segue: API proxy for the Apigee mock target service endpoint.
  8. Fai clic su Avanti.
  9. Nella pagina Criteri comuni, in Sicurezza: autorizzazione, assicurati che sia selezionata l'opzione Passa attraverso (nessuna autorizzazione) e fai clic su Avanti:

    Passthrough (nessuna autorizzazione) selezionato nella pagina Criteri comuni

  10. Nella pagina Flussi, assicurati che siano selezionate tutte le operazioni. Crea flussi proxy
  11. Fai clic su Avanti.
  12. Nella pagina Host virtuali, seleziona predefinito e protetto, quindi fai clic su Avanti.
    opzione predefinita e sicura selezionata nella pagina Host virtuali
  13. Nella pagina Riepilogo, assicurati che l'ambiente Test sia selezionato in Deployment facoltativo e fai clic su Crea ed esegui il deployment:

    Apigee crea il nuovo proxy API e ne esegue il deployment nell'ambiente di test:

  14. Fai clic su Modifica proxy per visualizzare la pagina Panoramica del proxy API.
    Riepilogo del proxy API target fittizio

Classic Edge (private cloud)

Per creare il proxy API da una specifica OpenAPI utilizzando l'interfaccia utente classica di Edge:

  1. Accedi ad https://apigee.com/edge.
  2. Fai clic su Proxy API nella finestra principale.

    In alternativa, puoi selezionare Sviluppo > Proxy API nella barra di navigazione a sinistra.

  3. Fai clic su + Proxy.
    Aggiungi proxy API
  4. Nella procedura guidata Crea proxy, seleziona Inverti proxy (più comune) e fai clic su Utilizza OpenAPI.
    Crea un tipo di proxy
  5. Fai clic su Importa da un URL, inserisci un nome per la specifica OpenAPI e inserisci il percorso dei contenuti non elaborati su GitHub per la specifica OpenAPI nel campo URL:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. Fai clic su Seleziona.
  7. Fai clic su Avanti.

    Viene visualizzata la pagina Dettagli nella procedura guidata Crea proxy. I campi vengono precompilati utilizzando i valori definiti nella specifica OpenAPI, come mostrato nella figura seguente.

    Dettagli build un proxy

    La seguente tabella descrive i valori predefiniti precompilati utilizzando le proprietà nella specifica OpenAPI. Di seguito la tabella è mostrato un estratto della specifica OpenAPI che illustra le proprietà utilizzate.

    Campo Descrizione Predefinito
    Nome proxy Nome del proxy API. Ad esempio: Mock-Target-API. Proprietà title della specifica OpenAPI con spazi sostituiti da trattini
    Percorso di base del proxy Componente del percorso che identifica in modo univoco questo proxy API all'interno dell'organizzazione. L'URL visibile al pubblico di questo proxy API è composto dal nome della tua organizzazione, da un ambiente in cui è stato eseguito il deployment del proxy API e da questo percorso di base. Ad esempio: http://myorg-test.apigee.net/mock-target-api Contenuti del campo Nome convertiti in lettere minuscole
    API esistente URL di destinazione richiamato per conto di questo proxy API. È possibile utilizzare qualsiasi URL accessibile tramite internet aperto. Ad esempio: http://mocktarget.apigee.net servers dalla specifica OpenAPI
    Descrizione Descrizione del proxy API. description dalla specifica OpenAPI

    Di seguito è riportato un estratto della specifica OpenAPI che mostra le proprietà utilizzate per precompilare i campi.

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  8. Modifica il campo Descrizione come segue: API proxy for the Apigee mock target service endpoint.
  9. Fai clic su Avanti.
  10. Nella pagina Flussi, assicurati che siano selezionate tutte le operazioni. Crea flussi proxy
  11. Fai clic su Avanti.
  12. Nella pagina Sicurezza, seleziona Pass-through (nessuno) come opzione di sicurezza e fai clic su Avanti.
  13. Nella pagina Host virtuali, assicurati che tutti gli host virtuali siano selezionati e fai clic su Avanti.
  14. Nella pagina Crea, assicurati che sia selezionato l'ambiente di test e fai clic su Crea e implementa.
  15. Nella pagina Riepilogo, viene visualizzata una conferma che il nuovo proxy API è stato creato correttamente e ne è stato eseguito il deployment nell'ambiente di test.
    Crea un riepilogo del proxy
  16. Fai clic su API di destinazione simulata per visualizzare la pagina Panoramica del proxy API.
    Riepilogo del proxy API target fittizio

Complimenti! Hai creato un proxy API da una specifica OpenAPI. Quindi, testalo per vedere come funziona.

Testare il proxy API

Puoi testare l'API Mock-Target-API utilizzando cURL o un browser web.

In una finestra del terminale, esegui il seguente comando cURL. Sostituisci il nome dell'organizzazione nell'URL.

curl http://<org_name>-test.apigee.net/mock-target-api

Risposta

Dovresti vedere la seguente risposta:

Hello, Guest!        

Complimenti! Hai creato un semplice proxy API da una specifica OpenAPI e lo hai testato.

Aggiungi un criterio da XML a JSON

Successivamente, aggiungerai il criterio da XML a JSON al flusso condizionale Visualizza risposta XML che è stato generato automaticamente quando hai creato il proxy API dalla specifica OpenAPI. Il criterio convertirà la risposta XML della destinazione in una risposta JSON.

Innanzitutto, chiama l'API in modo da poter confrontare i risultati con quelli ricevuti dopo aver aggiunto il criterio. In una finestra del terminale, esegui il seguente comando cURL. Stai chiamando la risorsa /xml del servizio di destinazione, che restituisce in modo nativo un semplice blocco di XML. Sostituisci il nome dell'organizzazione nell'URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Risposta

Dovresti vedere la seguente risposta:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Ora facciamo un'azione che converta la risposta XML in JSON. Aggiungi il criterio da XML a JSON al flusso condizionale Visualizza risposta XML nel proxy API.

  1. Fai clic sulla scheda Develop (Sviluppo) nell'angolo in alto a destra della pagina Panoramica dell'API simulata nell'interfaccia utente perimetrale.
    Scheda Sviluppatore
  2. Nel riquadro di navigazione a sinistra, in Endpoint proxy > predefiniti, fai clic sul flusso condizionale Visualizza risposta XML.
    Seleziona Visualizza risposta XML
  3. Fai clic sul pulsante +Passaggio in basso, corrispondente alla Risposta del flusso.
    Seleziona +Passaggio
    Si apre la finestra di dialogo Aggiungi passaggio in cui viene visualizzato un elenco classificato di tutti i criteri che puoi aggiungere.
  4. Scorri fino alla categoria Mediazione e seleziona Da XML a JSON.
    Finestra di dialogo Aggiungi passaggio
  5. Mantieni i valori predefiniti per Nome visualizzato e Nome.
  6. Fai clic su Aggiungi. Il criterio da XML a JSON viene applicato alla risposta.Criterio da XML a JSON in corso
  7. Fai clic su Salva.

Ora che hai aggiunto il criterio, chiama di nuovo l'API utilizzando cURL. Tieni presente che stai ancora chiamando la stessa risorsa /xml. Il servizio di destinazione restituisce comunque il blocco di XML, ma ora il criterio nel proxy API convertirà la risposta in JSON. Effettua questa chiamata:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Tieni presente che la risposta XML viene convertita in JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Complimenti! Hai testato l'esecuzione di un criterio aggiunto a un flusso condizionale.