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

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Qué aprenderás

En este instructivo, aprenderás a realizar lo siguiente:

Crear un proxy de la API de Edge desde una especificación de OpenAPI
Llamar al proxy de API mediante cURL
Agregar una política a un flujo condicional
Probar la invocación de la política con cURL

Aprenderás a crear un proxy de API de Apigee desde una especificación de OpenAPI con la IU de Apigee. 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 Especificación de OpenAPI.

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 compatible con el servicio de destino ficticio, consulta las API de muestra de Apigee

Requisitos

Antes de comenzar, debes completar los pasos en Descripción general y requisitos previos.
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 apigee/api-platform-samples.
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

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

Si usas la IU de Apigee en la consola de Cloud, selecciona Desarrollo de proxy > Proxies de API.

Si usas la IU clásica de Apigee, selecciona Desarrollar > Proxies de API y, en el panel Proxies, selecciona el entorno para el proxy.
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 Crear nuevo.
En el asistente para crear un proxy, haz clic en Usar OpenAPI Spec para la plantilla Revertir Proxy (más común).
Haga clic en URL e ingrese 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
```

Haga clic en Seleccionar.

Se muestra la página Proxy details 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 la especificación de OpenAPI:

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 se compone del nombre de dominio externo o interno y esta ruta base. Por ejemplo: `http://apitest.acme.com/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
...

En la página Detalles del proxy, 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 Apigee “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 Resumen, asegúrate de que un entorno 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:
Haz clic en Editar proxy para mostrar la página Resumen general del proxy de API.

Prueba el proxy de API

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

En el ejemplo anterior, YOUR_ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Busca el nombre de host del grupo de entornos.

Por ejemplo:

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

Respuesta

Debería ver la siguiente respuesta:

Hello, Guest!

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.

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

En el ejemplo anterior, YOUR ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Encuentra el nombre de host del grupo de entornos.

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.

Editor de proxies nuevo

Haz clic en la pestaña Desarrollar en la página Descripción general de la API de destino ficticia en la IU de Apigee.

Selecciona Ver respuesta de XML

En el panel de la izquierda, ve a Extremos del proxy > predeterminado y haz clic en el flujo condicional Ver respuesta de XML.
En el panel de la izquierda, haz clic en el botón + en la fila Políticas.
En el cuadro de diálogo Crear política, haz clic en el campo Seleccionar tipo de política, desplázate hacia abajo hasta mediación y selecciona XMLToJSON. Mantén los valores predeterminados para Nombre visible y Nombre.
Haz clic en Crear para crear la política.
Haz clic en el botón + junto al flujo Ver respuesta XML en Respuesta.
En el cuadro de diálogo Agregar paso de la política, haz clic en el campo Seleccionar política existente y selecciona XML a JSON-1.
Haz clic en Agregar. La política XML a JSON se aplica a la respuesta.

Para ver el código del flujo condicional Ver respuesta XML, haz clic en Cambiar al editor de código.
Haz clic en Guardar.

Editor de proxies clásico

Haz clic en la pestaña Desarrollar en la página Descripción general de la API de destino ficticia en la IU de Apigee.
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.
Haz clic en Guardar.

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

En el ejemplo anterior, YOUR ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Encuentra el nombre de host del grupo de entornos.

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

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