Crea un proxy de API a partir de una especificación de OpenAPI | Apigee Edge

En este instructivo, aprenderás a crear un proxy de API de Edge desde una especificación de OpenAPI con la IU de administración de Apigee Edge. Cuando llamas al proxy de API con un cliente HTTP, como cURL, el proxy de API envía la solicitud al servicio de destino ficticio de Apigee.

Información sobre Open API Initiative

"Open API Initiative (OAI) se enfoca en crear, desarrollar y promocionar un formato de descripción de API que no depende de los proveedores basado en la especificación de Swagger ". Para obtener más información sobre Open API Initiative, consulta https://openapis.org.

Una Especificación de OpenAPI usa un formato estándar para describir una API de RESTful. Una especificación de OpenAPI, que está escrita en formato JSON o YAML, es legible para las máquinas, pero también es fácil de leer y comprender. En la especificación, se describen elementos de una API como su ruta base, las rutas y verbos, los encabezados, los parámetros de consulta, las operaciones, los tipos de contenido, las descripciones de respuesta y más. Además, una especificación de OpenAPI se suele usar para generar documentación de la API.

Información sobre el servicio de destino ficticio de Apigee

El servicio de destino ficticio de Apigee que se usa en este instructivo se aloja en Apigee y muestra datos simples. No requiere una clave de API ni un token de acceso. De hecho, puedes acceder a él desde un navegador web. Haz clic en los siguientes vínculos para probarlo:

http://mocktarget.apigee.net

El servicio de destino muestra el saludo Hello, guest!

Para obtener información sobre el conjunto completo de API que admite el servicio de destino ficticio, haz clic en lo siguiente:

http://mocktarget.apigee.net/help

Requisitos

Una cuenta de Apigee Edge. Si no tienes una cuenta, puedes registrarte siguiendo las instrucciones en Crea una cuenta de Apigee Edge.
Una especificación de OpenAPI. En este instructivo, usarás la Especificación mocktarget.yaml de OpenAPI, que describe el servicio de destino ficticio de Apigee, http://mocktarget.apigee.net. Para obtener más información, consulta https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
cURL instalado en tu máquina para realizar llamadas a la API desde la línea de comandos o un navegador web.

Crea el proxy de API

Edge

Para crear el proxy de API a partir de una especificación de OpenAPI con la IU de Edge, sigue estos pasos:

Accede a https://apigee.com/edge.
Haz clic en Proxies de API en la ventana principal.
Como alternativa, puedes seleccionar Desarrollar > Proxies de API en el menú de navegación de la izquierda.
Haz clic en + Proxy.
En el asistente para crear un proxy, haz clic en Usar OpenAPI Spec para la plantilla Revertir Proxy (más común).
Haz clic en Importar desde URL y, luego, ingresa la siguiente información:
- URL de especificación de OpenAPI: Es la ruta de acceso al contenido sin procesar de GitHub para la especificación de OpenAPI en el campo URL.
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Nombre de la especificación: Nombre para la especificación OpenAPI, como destino ficticio.
  Este nombre se usa para almacenar la especificación de OpenAPI en el almacén de especificaciones. Consulta Administra tus especificaciones.

Haz clic en Importar.

Se muestra la página de detalles en el asistente de creación de proxy. Los campos se prepropagan con los valores definidos en la especificación de OpenAPI, como se muestra en la siguiente figura.

En la siguiente tabla, se describen los valores predeterminados que se propagan previamente mediante las propiedades de la especificación de OpenAPI. Después de la tabla, se muestra un extracto de la especificación de OpenAPI que ilustra las propiedades que se usan.

Campo	Descripción	Predeterminado
Nombre	Nombre del proxy de API. Por ejemplo: `Mock-Target-API`.	La propiedad `title` de la especificación de OpenAPI con espacios reemplazados por guiones
Ruta base	Componente de la ruta de acceso que identifica este proxy de API dentro de la organización de forma única. La URL pública de este proxy de API se compone del nombre de tu organización, un entorno en el que se implementa este proxy de API y esta ruta base. Por ejemplo: `http://myorg-test.apigee.net/mock-target-api`	Contenido del campo de nombre convertido en minúsculas
Descripción	Descripción del proxy de API.	La propiedad `description` de la especificación OpenAPI
(API existente) de destino	La URL de destino invocada en nombre de este proxy de API. Se puede usar cualquier URL a la que se pueda acceder a través de la Internet abierta. Por ejemplo: `http://mocktarget.apigee.net`	La propiedad `servers` de la especificación de OpenAPI

A continuación, se proporciona un extracto de la especificación de OpenAPI que muestra las propiedades que se usan para propagar previamente los campos.

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
...

Edita el campo Descripción de la siguiente manera: API proxy for the Apigee mock target service endpoint.
Haga clic en Next.
En la página Políticas comunes, en Seguridad: autorización, asegúrate de que la opción Pasar (sin autorización) esté seleccionada y haz clic en A continuación:
En la página Flows, asegúrate de que todas las operaciones estén seleccionadas.
Sugerencia: Los flujos condicionales se generan de forma automática a partir de las operaciones definidas en el objeto paths en la especificación de OpenAPI. Los flujos condicionales le indican a Edge “Cuando veas esto, realiza esta lógica”. Por ejemplo, cuando una llamada a la API es GET en el recurso /xml (la condición), transforma la respuesta a JSON (a través de una política adjunta al flujo condicional). Solo se ejecuta un flujo por transacción; el primer flujo cuya condición se evalúa como verdadera.
Haz clic en Siguiente (Next).
En la página Hosts virtuales, selecciona configuración predeterminada y seguro, y haz clic Siguiente.
En la página Resumen, asegúrate de que el entorno Prueba esté seleccionado en Implementación opcional y haz clic en Crear e implementar:

Apigee crea tu nuevo proxy de API y lo implementa en tu entorno de prueba:
Haz clic en Editar proxy para mostrar la página de descripción general del proxy de API proxy.

Classic Edge (nube privada)

Para crear el proxy de API a partir de una especificación de OpenAPI con la IU de Classic Edge, sigue estos pasos:

Accede a https://apigee.com/edge.
Haz clic en Proxies de API en la ventana principal.
Como alternativa, puedes seleccionar Desarrollar > Proxies de API en el menú de navegación de la izquierda.
Haz clic en + Proxy.
En el asistente de creación de proxy, selecciona Proxy inverso (más común) y haz clic en Usar OpenAPI.
Haz clic en Importar desde una URL, ingresa un nombre para la especificación de OpenAPI y, luego, ingresa la ruta de acceso al contenido sin procesar de GitHub para la especificación de OpenAPI en el campo URL:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Haz clic en Seleccionar.

Haga clic en Next.

Se muestra la página de detalles en el asistente de creación de proxy. Los campos se prepropagan con los valores definidos en la especificación de OpenAPI, como se muestra en la siguiente figura.

En la siguiente tabla, se describen los valores predeterminados que se propagan previamente mediante las propiedades de la especificación de OpenAPI. Después de la tabla, se muestra un extracto de la especificación de OpenAPI que ilustra las propiedades que se usan.

Campo	Descripción	Predeterminado
Proxy name	Nombre del proxy de API. Por ejemplo: `Mock-Target-API`.	La propiedad `title` de la especificación de OpenAPI con espacios reemplazados por guiones
Ruta base del proxy	Componente de la ruta de acceso que identifica este proxy de API dentro de la organización de forma única. La URL pública de este proxy de API se compone del nombre de tu organización, un entorno en el que se implementa este proxy de API y esta ruta base. Por ejemplo: `http://myorg-test.apigee.net/mock-target-api`	Contenido del campo de nombre convertido en minúsculas
Existing API	La URL de destino invocada en nombre de este proxy de API. Se puede usar cualquier URL a la que se pueda acceder a través de la Internet abierta. Por ejemplo: `http://mocktarget.apigee.net`	La propiedad `servers` de la especificación de OpenAPI
Descripción	Descripción del proxy de API.	La propiedad `description` de la especificación OpenAPI

A continuación, se proporciona un extracto de la especificación de OpenAPI que muestra las propiedades que se usan para propagar previamente los campos.

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
...

Edita el campo Descripción de la siguiente manera: API proxy for the Apigee mock target service endpoint.
Haga clic en Next.
En la página Flows, asegúrate de que todas las operaciones estén seleccionadas.
Sugerencia: Los flujos condicionales se generan de forma automática a partir de las operaciones definidas en el objeto paths en la especificación de OpenAPI. Los flujos condicionales le indican a Edge “Cuando veas esto, realiza esta lógica”. Por ejemplo, cuando una llamada a la API es GET en el recurso /xml (la condición), transforma la respuesta a JSON (a través de una política adjunta al flujo condicional). Solo se ejecuta un flujo por transacción; el primer flujo cuya condición se evalúa como verdadera.
Haga clic en Next.
En la página Security, selecciona Pass through (none) como la opción de seguridad y haz clic en Next.
En la página Virtual Hosts, asegúrate de que todos los hosts virtuales estén seleccionados y haz clic en Next.
En la página Compila, asegúrate de que el entorno prueba esté seleccionado y haz clic en Compilar e/o implementar.
En la página Resumen, verás una confirmación de que tu proxy de API nuevo se creó correctamente y se implementó en tu entorno de prueba.
Haz clic en Mock-Target-API para mostrar la página de descripción general del proxy de API.

¡Felicitaciones! Creaste un proxy de API a partir de una especificación de OpenAPI. A continuación, lo probarás para ver cómo funciona.

Prueba el proxy de API

Puedes probar tu API de Mock-Target-API con cURL o un navegador web.

En una ventana de terminal, ejecuta el siguiente comando de cURL. Sustituye el nombre de tu organización en la URL.

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

Respuesta

Debería ver la siguiente respuesta:

Hello, Guest!

¡Buen trabajo! Compilaste un proxy de API simple a partir de una especificación de OpenAPI y lo probaste.

Agrega una política de XML a JSON

A continuación, agregarás la política de XML a JSON al flujo condicional Ver respuesta de XML, que se generó automáticamente cuando creaste el proxy de API desde la especificación de OpenAPI. La política convertirá la respuesta XML del destino en una respuesta JSON.

Primero, llama a la API para que puedas comparar los resultados con los que se reciben después de agregar la política. En una ventana de terminal, ejecuta el siguiente comando de cURL. Estás llamando al recurso /xml del servicio de destino, que muestra de forma nativa un bloque simple de XML. Sustituye el nombre de tu organización en la URL.

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

Respuesta

Deberías ver la siguiente respuesta:

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

Ahora hagamos algo que convierta la respuesta XML en JSON. Agrega la política de XML a JSON al flujo condicional Ver respuesta de XML del proxy de API.

Haz clic en la pestaña Desarrollo en la esquina superior derecha de la página Descripción general de la API de destino en la IU perimetral.
En el panel del navegador de la izquierda, vaya a Extremos del proxy > predeterminado y haga clic en el flujo condicional Ver respuesta de XML.
Haz clic en el botón +Paso inferior, que corresponde a la Respuesta del flujo.

Se abrirá el cuadro de diálogo Agregar paso para mostrar una lista categorizada de todas las políticas que puedes agregar.
Desplázate hasta la categoría Mediación y selecciona XML a JSON.
Mantén los valores predeterminados para Nombre visible y Nombre.
Haz clic en Agregar. La política XML a JSON se aplica a la respuesta.
Haga clic en Save.

Ahora que agregaste la política, vuelve a llamar a la API con cURL. Ten en cuenta que aún llamas al mismo recurso /xml. El servicio de destino volverá a mostrar su bloque de XML, pero ahora la política en el proxy de API convertirá la respuesta a JSON. Haz esta llamada:

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

Ten en cuenta que la respuesta XML se convierte a JSON:

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

¡Felicitaciones! Probaste correctamente la ejecución de una política agregada a un flujo condicional.