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 a partir de una OpenAPI Especificación que usa 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 el en Crea un entorno de Apigee Edge cuenta de servicio.
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 la URL e ingresa la siguiente información:
- URL de especificaciones de OpenAPI: Ruta de acceso al contenido sin procesar en 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 Administrar tus especificaciones.

Haga clic en Import.

Se mostrará la página Detalles del asistente de creación de proxy. Los campos se prepropagaron con valores definidos en la Especificación de OpenAPI, como se muestra en el siguiente

En la siguiente tabla, se describen los valores predeterminados que se prepropagan usando en la especificación de OpenAPI. Un extracto de la especificación de OpenAPI con las propiedades que se usan se muestra después de la tabla.

Campo	Descripción	Predeterminada
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 está compuesta por el nombre de tu organización, una en el que se implementa el proxy de API y esta ruta base. Para 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 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 Description 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 Siguiente:
En la página Flujos, asegúrate de que todas las operaciones estén seleccionadas.
Nota: Los flujos condicionales se generan automáticamente a partir de las operaciones que se definen dentro del objeto paths en OpenAPI Especificación. Los flujos condicionales le indican a Edge lo siguiente: "Cuando veas esto, aplica esta lógica". Por ejemplo, cuando una llamada a la API es GET en el recurso /xml (la condición), transformar la respuesta en 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 true.
Haz clic en Siguiente (Next).
En la página Hosts virtuales, selecciona configuración predeterminada y seguro, y haz clic en Siguiente.
En la página Summary, asegúrate de que el entorno de Test sea en Implementación opcional y haz clic en Crear y deploy:

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

Classic Edge (nube privada)

Para crear el proxy de API a partir de una especificación de OpenAPI con la IU clásica 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 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 en GitHub para la OpenAPI Especificación en el campo URL:

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

Haz clic en Siguiente.

Se mostrará la página Detalles del asistente de creación de proxy. Los campos se prepropagaron con valores definidos en la Especificación de OpenAPI, como se muestra en el siguiente figura.

En la siguiente tabla, se describen los valores predeterminados que se prepropagan usando en la especificación de OpenAPI. Un extracto de la especificación de OpenAPI con las propiedades que se usan se muestra después de la tabla.

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 está compuesta por el nombre de tu organización, una en el que se implementa el proxy de API y esta ruta base. Para 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 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 Description de la siguiente manera: API proxy for the Apigee mock target service endpoint.
Haz clic en Siguiente.
En la página Flujos, asegúrate de que todas las operaciones estén seleccionadas.
Nota: Los flujos condicionales se generan automáticamente a partir de las operaciones que se definen dentro del objeto paths en OpenAPI Especificación. Los flujos condicionales le indican a Edge lo siguiente: "Cuando veas esto, aplica esta lógica". Por ejemplo, cuando una llamada a la API es GET en el recurso /xml (la condición), transformar la respuesta en 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 true.
Haz clic en Siguiente.
En la página Seguridad, selecciona Pasar (ninguno) como el y haz clic en Siguiente.
En la página Virtual Hosts, asegúrese de que todos los hosts virtuales estén seleccionados y haga clic en Siguiente.
En la página Compila, asegúrate de que el entorno prueba esté seleccionado y haz clic en Compilar e implementar.
En la página Resumen, verás una confirmación de que se creó tu nuevo proxy de API. de forma correcta y se implementaron en tu entorno de pruebas.
Haz clic en Mock-Target-API para mostrar la página Overview de la API. proxy.

¡Felicitaciones! Creaste un proxy de API a partir de una especificación de OpenAPI. A continuación, y pruébalo 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 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ía 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 Media y selecciona XML a JSON.
Mantén los valores predeterminados para Display Name (Nombre visible) y Nombre:
Haz clic en Agregar. La política de 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.