Creazione di un proxy API da una specifica OpenAPI | Apigee

Imparerai come creare un proxy API Apigee da una specifica OpenAPI utilizzando l'UI di Apigee. 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

"L'Open API Initiative (OAI) è incentrata sulla creazione, sull'evoluzione e sulla promozione di un formato di descrizione dell'API indipendente dal fornitore e basato sulla specifica Swagger." Per ulteriori informazioni sull'iniziativa Open API, consulta la pagina La specifica OpenAPI.

Una specifica OpenAPI utilizza un formato standard per descrivere un'API RESTful. Scritta in formato JSON o YAML, una specifica OpenAPI è leggibile dalle macchine, ma è anche di facile lettura e comprensione per gli esseri umani. La specifica descrive questi elementi di un'API come percorso di base, percorsi e verbi, intestazioni, parametri di ricerca, operazioni, tipi di contenuti, descrizioni delle risposte e altro ancora. Inoltre, una specifica OpenAPI viene comunemente utilizzata per generare documentazione API.

Informazioni sul servizio di destinazione simulato 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. Puoi infatti 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 sull'insieme completo di API supportate dal servizio di destinazione fittizio, consulta API di esempio Apigee

Che cosa ti serve

Prima di iniziare, devi completare i passaggi descritti in Panoramica e prerequisiti.
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 ulteriori informazioni, consulta apigee/api-platform-samples.
cURL installato sulla tua macchina per effettuare chiamate API dalla riga di comando o da un browser web.

Crea il proxy API

Per creare il proxy API da una specifica OpenAPI:

Se utilizzi https://console.cloud.google.com/apigee: seleziona Sviluppo proxy > Proxy API.

Se utilizzi l'interfaccia utente di Apigee classica: seleziona Sviluppo > Proxy API e, nel riquadro proxy, seleziona l'ambiente per il proxy.
Fai clic su Proxy API nella finestra principale.
In alternativa, puoi selezionare Sviluppo > Proxy API nella barra di navigazione a sinistra.
Fai clic su Crea nuovo.
Nella procedura guidata Crea proxy, fai clic su Utilizza specifica OpenAPI per il modello proxy inverso (più comune).
Fai clic su URL e inserisci le seguenti informazioni:
OpenAPI Spec URL (URL specifica OpenAPI): 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
```

Fai clic su Seleziona.

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

La seguente tabella descrive i valori predefiniti precompilati utilizzando la specifica OpenAPI:

Campo	Descrizione	Predefinito
Nome	Nome del proxy API. Ad esempio: `Mock-Target-API`.	`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 pubblico di questo proxy API è composto dal nome di dominio esterno o interno e da questo percorso di base. Ad esempio: `http://apitest.acme.com/mock-target-api`	Contenuti del campo Nome convertiti in lettere minuscole
Description	Descrizione del proxy API.	`description` della specifica OpenAPI
Target (API esistente)	URL di destinazione richiamato per conto di questo proxy API. È possibile utilizzare qualsiasi URL accessibile tramite internet. Ad esempio: `http://mocktarget.apigee.net`	`servers` della 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
...

Nella pagina Dettagli proxy, modifica il campo Descrizione come segue:
```
API proxy for the Apigee mock target service endpoint.
```
Tocca Avanti.
Nella pagina Criteri comuni, in Sicurezza: autorizzazione, assicurati che sia selezionata l'opzione Passthrough (nessuna autorizzazione) e fai clic su Avanti:
Nella pagina Flows (Flussi), assicurati che siano selezionate tutte le operazioni.
Suggerimento: i flussi condizionali vengono generati automaticamente dalle operazioni definite all'interno dell'oggetto paths nella specifica OpenAPI. I flussi condizionali indicano ad Apigee "Quando vedi questo messaggio, esegui questa logica". Ad esempio, quando una chiamata API è GET nella risorsa /xml (la condizione), trasforma la risposta in JSON (tramite un criterio collegato al flusso condizionale). Viene eseguito un solo flusso per transazione, il primo la cui condizione è considerata true.
Tocca Avanti.
Nella pagina Riepilogo, assicurati che sia selezionato un ambiente in Deployment facoltativo e fai clic su Crea ed esegui il deployment:

Apigee crea il tuo nuovo proxy API e ne esegue il deployment nel tuo ambiente:
Fai clic su Modifica proxy per visualizzare la pagina Panoramica relativa al proxy API.

Testa il proxy API

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

dove YOUR_ENV_GROUP_HOSTNAME è il nome host del tuo gruppo di ambienti. Vedi Trovare il nome host del gruppo di ambienti.

Ad esempio:

curl -v -k https://apitest.acme.com/myproxy

Risposta

Dovresti vedere la seguente risposta:

Hello, Guest!

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 del target 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 comando cURL riportato di seguito. Stai chiamando la risorsa /xml del servizio di destinazione, che restituisce in modo nativo un semplice blocco di XML.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

dove YOUR ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti. Vedi Trovare il nome host del gruppo di ambienti.

Risposta

Dovresti vedere la seguente risposta:

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

Proviamo a convertire la risposta XML in JSON. Aggiungi il criterio da XML a JSON al flusso condizionale di risposta XML nel proxy API.

Nuovo editor proxy

Fai clic sulla scheda Develop nella pagina Mock-Target-API Overview (Panoramica API target simulata) dell'interfaccia utente di Apigee.

Seleziona Visualizza risposta XML

Nel riquadro a sinistra, in Endpoint proxy > predefinito, fai clic sul flusso condizionale Visualizza risposta XML.
Nel riquadro a sinistra, fai clic sul pulsante + nella riga Norme.
Nella finestra di dialogo Crea criterio, fai clic sul campo Seleziona il tipo di criterio, scorri verso il basso fino a Mediazione e seleziona XMLToJSON. Mantieni i valori predefiniti per Nome visualizzato e Nome.
Fai clic su Crea per creare il criterio.
Fai clic sul pulsante + accanto al flusso Visualizza risposta XML nella Risposta.
Nella finestra di dialogo Aggiungi passaggio per il criterio, fai clic sul campo Seleziona criterio esistente e seleziona XML to JSON-1.
Fai clic su Aggiungi. Il criterio da XML a JSON viene applicato alla risposta.

Per visualizzare il codice per il flusso condizionale Visualizza risposta XML, fai clic su Passa all'editor di codice.
Fai clic su Salva.

Editor proxy classico

Fai clic sulla scheda Develop nella pagina Mock-Target-API Overview (Panoramica API target simulata) dell'interfaccia utente di Apigee.
Nel riquadro di navigazione a sinistra, in Endpoint del proxy > predefinito, fai clic sul flusso condizionale Visualizza risposta XML.
Fai clic sul pulsante +Passaggio in basso, corrispondente alla Risposta per il flusso.

Si apre la finestra di dialogo Aggiungi passaggio per visualizzare un elenco categorizzato di tutti i criteri che puoi aggiungere.
Scorri fino alla categoria Mediazione e seleziona Da XML a JSON.
Mantieni i valori predefiniti per Nome visualizzato e Nome.
Fai clic su Aggiungi. Il criterio da XML a JSON viene applicato alla risposta.
Fai clic su Salva.

Dopo aver 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 -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

dove YOUR ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti. Vedi Trovare il nome host del gruppo di ambienti.

Tieni presente che la risposta XML viene convertita in JSON:

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