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

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

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

En este instructivo, aprenderás a crear un proxy de API de Edge a partir de una especificación de OpenAPI mediante 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
"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 seguir las instrucciones en Crea una cuenta de Apigee Edge para registrarte.
  • 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

Conexión de integración

Para crear el proxy de API a partir de una especificación de OpenAPI con la IU de Edge, haz lo siguiente:

  1. Accede a https://apigee.com/edge.
  2. En la ventana principal, haz clic en Proxies de API.

    También puedes seleccionar Develop > API Proxies en la barra de navegación izquierda.

    Haz clic en proxies de API en la página de destino

  3. Haz clic en + Proxy.
    Agrega el proxy de API
  4. En el asistente de creación de proxy, haz clic en Usar especificación de OpenAPI para la plantilla Proxy inverso (más común).
    Compila un tipo de proxy
  5. Haz clic en Importar desde URL y, luego, ingresa la siguiente información:
    • URL de especificación 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.

  6. Haz clic en Importar.

    Se mostrará la página Detalles del asistente de creación de proxy. Los campos se propagan previamente con valores definidos en la especificación de OpenAPI, como se muestra a continuación.

    En la siguiente tabla, se describen los valores predeterminados que se propagan previamente con las propiedades en la especificación de OpenAPI. A continuación de la tabla, se muestra un extracto de la especificación de OpenAPI que ilustra las propiedades utilizadas.

    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 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 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
    ...
    
  7. Edita el campo Descripción de la siguiente manera: API proxy for the Apigee mock target service endpoint.
  8. Presiona Siguiente.
  9. En la página Políticas comunes, en Seguridad: Autorización, asegúrese de que esté seleccionada la opción Transferencia (sin autorización) y, luego, haga clic en Siguiente:

    Se seleccionó un traspaso (sin autorización) en la página Políticas comunes

  10. En la página Flujos, asegúrate de que todas las operaciones estén seleccionadas. Compila flujos de proxy
  11. Presiona Siguiente.
  12. En la página Hosts virtuales, selecciona default y secure, y haz clic en Siguiente.
    de forma predeterminada y segura seleccionada en la página Hosts virtuales
  13. 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 pruebas:

  14. Haz clic en Editar proxy para mostrar la página Descripción general del proxy de API.
    Resumen del proxy de la API de destino ficticio

Versión clásica de 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:

  1. Accede a https://apigee.com/edge.
  2. En la ventana principal, haz clic en Proxies de API.

    También puedes seleccionar Develop > API Proxies en la barra de navegación izquierda.

  3. Haz clic en + Proxy.
    Agrega el proxy de API
  4. En el asistente de creación de proxy, selecciona Revertir proxy (más común) y haz clic en Usar OpenAPI.
    Compila un tipo de proxy
  5. Haz clic en Importar desde una URL, ingresa un nombre para la especificación de OpenAPI y la ruta de acceso al contenido sin procesar en GitHub de la especificación de OpenAPI en el campo URL:

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

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

    Detalles de la compilación de un proxy

    En la siguiente tabla, se describen los valores predeterminados que se propagan previamente con las propiedades en la especificación de OpenAPI. A continuación de la tabla, se muestra un extracto de la especificación de OpenAPI que ilustra las propiedades utilizadas.

    Campo Descripción Predeterminada
    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 de acceso 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 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
    ...
    
  8. Edita el campo Descripción de la siguiente manera: API proxy for the Apigee mock target service endpoint.
  9. Presiona Siguiente.
  10. En la página Flujos, asegúrate de que todas las operaciones estén seleccionadas. Compila flujos de proxy
  11. Presiona Siguiente.
  12. En la página Seguridad, selecciona Transferir (ninguno) como la opción de seguridad y haz clic en Siguiente.
  13. En la página Virtual Hosts, asegúrate de que todos los hosts virtuales estén seleccionados y haz clic en Next.
  14. En la página Compila, asegúrate de que el entorno prueba esté seleccionado y haz clic en Compilar e implementar.
  15. En la página Resumen, verás una confirmación de que tu proxy de API nuevo se creó y se implementó de forma correcta en el entorno de pruebas.
    Resumen de la creación de un proxy
  16. Haz clic en Mock-Target-API para mostrar la página Descripción general del proxy de API.
    Resumen del proxy de la API de destino ficticio

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

  1. Haz clic en la pestaña Develop en la esquina superior derecha de la página de resumen de Mock-Target-API en la IU de Edge.
    Pestaña Desarrollar
  2. En el panel del navegador de la izquierda, en Proxy Endpoints > default, haz clic en el flujo condicional View XML Response.
    Selecciona Ver respuesta de XML
  3. Haz clic en el botón +Paso inferior, que corresponde a la Respuesta del flujo.
    Seleccionar +Paso
    Se abrirá el cuadro de diálogo Agregar paso para mostrar una lista categorizada de todas las políticas que puedes agregar.
  4. Desplázate hasta la categoría Mediación y selecciona XML to JSON.
    Diálogo Agregar paso
  5. Mantén los valores predeterminados de Display Name y Name.
  6. Haz clic en Agregar. Se aplica la política de XML a JSON a la respuesta.Política XML a JSON en el flujo
  7. 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 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 con éxito la ejecución de una política agregada a un flujo condicional.