Creazione di un proxy API da una specifica OpenAPI

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza Apigee Edge documentazione.

Cosa imparerai a fare

In questo tutorial imparerai a:

Creare un proxy API Apigee da una specifica OpenAPI.
Chiamare il proxy API utilizzando cURL.
Aggiungere una policy a un flusso condizionale.
Testare la chiamata della policy utilizzando cURL.

Imparerai a creare un proxy API Apigee da una specifica OpenAPI utilizzando l'interfaccia utente di Apigee. Quando chiami il proxy API con un client HTTP, ad esempio cURL, il proxy API invia la richiesta al servizio target di simulazione di Apigee.

Informazioni sull'iniziativa Open API

"L'iniziativa Open API (OAI) è incentrata sulla creazione, l'evoluzione e la promozione di un formato di descrizione API indipendente dal fornitore basato sulla specifica Swagger ." Per saperne di più sull'iniziativa Open API, consulta 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 dalla macchina, ma è anche facile da leggere e comprendere per le persone. La specifica descrive elementi di un API come il percorso di base, i percorsi e i verbi, le intestazioni, i parametri di ricerca, le operazioni, i 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 di Apigee

Il servizio target di simulazione di Apigee utilizzato in questo tutorial è ospitato su Apigee e restituisce dati semplici. Non richiede una chiave API o un token di accesso. Infatti, puoi accedervi in un browser web. Provalo facendo clic su:

http://mocktarget.apigee.net

Il servizio target restituisce il saluto Hello, guest!

Per informazioni sull'insieme completo di API supportate dal servizio target di simulazione, consulta API di esempio di 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 target di simulazione di Apigee, http://mocktarget.apigee.net. Per saperne di più, consulta apigee/api-platform-samples.
cURL installato sulla tua macchina per effettuare chiamate API dalla riga di comando o un browser web.

Creare il proxy API

Per creare il proxy API da una specifica OpenAPI:

Nella Google Cloud console, vai alla pagina Apigee > Sviluppo proxy > Proxy API.

Vai ai proxy API
Nel riquadro Proxy API, fai clic su + Crea.
Nel riquadro Crea un proxy, in Modello proxy > Modello di specifica OpenAPI, seleziona Proxy inverso (più comune).

Vai al seguente URL nel browser web:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

Fai clic con il tasto destro del mouse sul codice visualizzato e seleziona Salva con nome.
Fai clic su Salva per salvare mocktarget3.0.yaml nella posizione desiderata.
Nel campo Specifiche OpenAPI, fai clic sul pulsante Sfoglia.
Vai al file mocktarget3.0.yaml e fai clic su Apri.
Fai clic su Avanti.
Il passaggio Dettagli proxy della procedura guidata Crea proxy compila automaticamente i campi con i valori estratti direttamente dalla specifica OpenAPI.

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

Campo	Descrizione	Predefinito
Nome proxy	Nome del proxy API. Ad esempio: `Mock-Target-API`.	Proprietà `title` della specifica OpenAPI con gli spazi sostituiti da trattini
Percorso di 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`	Contenuto del campo Nome convertito in minuscolo
Descrizione	Descrizione del proxy API.	Proprietà `description` della 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`	Proprietà `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
      ...

Nel passaggio Dettagli proxy, modifica il campo Descrizione come segue:
```
API proxy for the Apigee mock target service endpoint.
```
Fai clic su Avanti.
Nel passaggio Flussi, assicurati che tutte le operazioni siano selezionate.
Suggerimento: i flussi condizionali vengono generati automaticamente dalle operazioni definite nell'oggetto paths della specifica OpenAPI. I flussi condizionali indicano ad Apigee: "Quando vedi questo, esegui questa logica". Ad esempio, quando una chiamata API è un GET sulla risorsa /xml (la condizione), trasforma la risposta in JSON (tramite una policy collegata al flusso condizionale). Per ogni transazione viene eseguito un solo flusso: il primo flusso la cui condizione restituisce true.
Fai clic su Avanti.
Nel passaggio Esegui il deployment , seleziona uno o più ambienti e fai clic su Ok.
Fai clic su Crea.

Testare 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 gruppo di ambienti. Consulta 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!

Aggiungere una policy da XML a JSON

Ora aggiungerai la policy da XML a JSON al flusso condizionale Visualizza risposta XML generato automaticamente quando hai creato il proxy API dalla specifica OpenAPI. La policy convertirà la risposta XML del target in una risposta JSON response.

Innanzitutto, chiama l'API in modo da poter confrontare i risultati con quelli ricevuti dopo aver aggiunto la policy. In una finestra del terminale, esegui il seguente comando cURL. Stai chiamando la risorsa /xml del servizio target, 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. Consulta 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>

Ora facciamo qualcosa che converta la risposta XML in JSON. Aggiungi la policy da XML a JSON al flusso condizionale Visualizza risposta XML nel proxy API.

Fai clic sulla scheda Sviluppa nella pagina Panoramica di Mock-Target-API nell'interfaccia utente di Apigee.

Seleziona Visualizza risposta XML

Nel riquadro a sinistra, in Endpoint proxy > default, fai clic sul flusso condizionale Visualizza risposta XML.
Nel riquadro a sinistra, fai clic sul pulsante + nella riga Policy.
Nella finestra di dialogo Crea policy , fai clic sul campo Seleziona tipo di policy , 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 la policy.
Fai clic sul pulsante + accanto al flusso Visualizza risposta XML in Risposta.
Nella finestra di dialogo Aggiungi passaggio policy, fai clic sul campo Seleziona policy esistente e seleziona XML to JSON-1.
Fai clic su Aggiungi. La policy da XML a JSON viene applicata alla risposta.

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

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

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