Crear un proxy de APIs 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é vas a aprender

En este tutorial, aprenderás a hacer lo siguiente:

  • Crea un proxy de API de Apigee a partir de una especificación de OpenAPI.
  • Llama al proxy de API con cURL.
  • Añade una política a un flujo condicional.
  • Prueba la invocación de la política con cURL.

Aprenderás a crear un proxy de API de Apigee a partir de una especificación de OpenAPI con la interfaz de usuario 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 simulado de Apigee.

Acerca de la iniciativa de API abierta

Iniciativa de APIs abiertas

"La iniciativa de API abierta (OAI) se centra en crear, desarrollar y promover un formato de descripción de API independiente del proveedor basado en la especificación de Swagger". Para obtener más información sobre la iniciativa de API abierta, consulta Especificación de OpenAPI.

Una especificación de OpenAPI usa un formato estándar para describir una API RESTful. Escrita en formato JSON o YAML, una especificación de OpenAPI es legible por máquinas, pero también es fácil de leer y entender para los humanos. La especificación describe elementos de una API, como su ruta base, rutas y verbos, encabezados, parámetros de consulta, operaciones, tipos de contenido, descripciones de respuestas y más. Además, se suele usar una especificación de OpenAPI para generar documentación de la API.

Acerca del servicio de destino simulado de Apigee

El servicio de destino simulado de Apigee que se usa en este tutorial está alojado en Apigee y devuelve datos sencillos. No requiere ninguna clave de API ni token de acceso. De hecho, puedes acceder a ella en un navegador web. Para probarlo, haz clic en lo siguiente:

http://mocktarget.apigee.net

El servicio de destino devuelve el saludo Hello, guest!

Para obtener información sobre el conjunto completo de APIs que admite el servicio de destino simulado, consulta APIs de ejemplo de Apigee.

Qué se necesita

  • Antes de empezar, debes completar los pasos que se indican en el artículo Descripción general y requisitos.
  • Una especificación de OpenAPI. En este tutorial, usarás la mocktarget.yaml especificación de OpenAPI, que describe el servicio de destino simulado de Apigee, http://mocktarget.apigee.net. Para obtener más información, consulta apigee/api-platform-samples.
  • cURL instalado en tu máquina para hacer llamadas a la API desde la línea de comandos o un navegador web.

Crear el proxy de API

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

Apigee en la consola de Cloud

  1. En la Google Cloud consola, ve a la página Desarrollo de proxy > Proxies de API.

    Ir a proxies de API

  2. En el panel Proxies de APIs, haz clic en + Crear.
  3. En el panel Crear un proxy, en Plantilla de proxy > Plantilla de especificación de OpenAPI, selecciona Proxy inverso (el más habitual).
  4. Ve a la siguiente URL en tu navegador web: 
    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  5. Haz clic con el botón derecho en el código que se muestra y selecciona Guardar como.
  6. Haz clic en Guardar para guardar el mocktarget3.0.yaml en la ubicación que quieras.
  7. En el campo Especificaciones de OpenAPI, haga clic en el botón Buscar.
  8. Ve al archivo mocktarget3.0.yaml y haz clic en Abrir.
  9. Haz clic en Siguiente.
  10. En el paso Detalles del proxy del asistente Crear proxy, los campos se rellenan automáticamente con los valores extraídos directamente de la especificación de OpenAPI.

    11. En la siguiente tabla se describen los valores predeterminados que se rellenan automáticamente mediante la especificación de OpenAPI:

    Campo Descripción Predeterminado
    Nombre del proxy Nombre del proxy de API. Por ejemplo: Mock-Target-API. Propiedad title de la especificación de OpenAPI con los espacios sustituidos por guiones
    Ruta base Componente de ruta que identifica de forma única este proxy de API en la organización. La URL pública de este proxy de API se compone de tu nombre de dominio externo o interno y de esta ruta base. Por ejemplo: http://apitest.acme.com/mock-target-api El contenido del campo Nombre se ha convertido a minúsculas
    Descripción Descripción del proxy de API. Propiedad description de la especificación de OpenAPI
    Destino (API actual) URL de destino invocado en nombre de este proxy de API. Se puede usar cualquier URL accesible a través de Internet. Por ejemplo: http://mocktarget.apigee.net Propiedad servers de la especificación de OpenAPI

    A continuación, se muestra un fragmento de la especificación OpenAPI que muestra las propiedades que se usan para rellenar 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
      ...
  11. En el paso Detalles del proxy, edita el campo Descripción de la siguiente manera: 
    API proxy for the Apigee mock target service endpoint.
  12. Haz clic en Siguiente.
  13. En el paso Flujos, asegúrate de que estén seleccionadas todas las operaciones.
  14. Haz clic en Siguiente.
  15. En el paso Implementar, seleccione uno o varios entornos y haga clic en Aceptar.
  16. Haz clic en Crear.

UI clásica de Apigee

  1. Selecciona Desarrollo > Proxies de API y, en el panel Proxies, selecciona el entorno del proxy.
  2. En la ventana principal, haz clic en Proxies de API.

    También puede seleccionar Desarrollar > Proxies de API en la barra de navegación de la izquierda.

    Hacer clic en Proxies de API en la página de destino

  3. Haz clic en Crear.

    Añadir un proxy de API

  4. En el asistente Crear proxy, haga clic en Usar especificación de OpenAPI para la plantilla Proxy inverso (la más habitual).

    Crear un tipo de proxy
  5. Haz clic en URL e introduce la siguiente información:

    URL de la especificación de OpenAPI: ruta al contenido sin formato 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/mocktarget3.0.yaml
  6. Haz clic en Seleccionar.

    Se muestra la página Detalles del proxy del asistente Crear proxy. Los campos se rellenan automáticamente con los valores definidos en la especificación de OpenAPI, tal como se muestra en la siguiente figura:

    En la siguiente tabla se describen los valores predeterminados que se rellenan automáticamente mediante la especificación de OpenAPI:

    Campo Descripción Predeterminado
    Nombre Nombre del proxy de API. Por ejemplo: Mock-Target-API. Propiedad title de la especificación de OpenAPI con los espacios sustituidos por guiones
    Ruta base Componente de ruta que identifica de forma única este proxy de API en la organización. La URL pública de este proxy de API se compone de tu nombre de dominio externo o interno y de esta ruta base. Por ejemplo: http://apitest.acme.com/mock-target-api El contenido del campo Nombre se ha convertido a minúsculas
    Descripción Descripción del proxy de API. Propiedad description de la especificación de OpenAPI
    Destino (API actual) URL de destino invocado en nombre de este proxy de API. Se puede usar cualquier URL accesible a través de Internet. Por ejemplo: http://mocktarget.apigee.net Propiedad servers de la especificación de OpenAPI

    A continuación, se muestra un fragmento de la especificación OpenAPI que muestra las propiedades que se usan para rellenar 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. 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.
  8. Haz clic en Siguiente.
  9. En la página Políticas comunes, en Seguridad: autorización, comprueba que esté seleccionada la opción Transferencia (sin autorización) y haz clic en Siguiente:

    Opción de transferencia (sin autorización) seleccionada en la página Políticas comunes

  10. En la página Flujos, asegúrate de que estén seleccionadas todas las operaciones. Crear un flujo proxy
  11. Haz clic en Siguiente.
  12. En la página Resumen, comprueba que se haya seleccionado un entorno en Implementación opcional y haz clic en Crear e implementar:

    Apigee crea el nuevo proxy de API y lo despliega en tu entorno:

  13. Haz clic en Editar proxy para mostrar la página Descripción general del proxy de API.

Probar el proxy de APIs

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

donde YOUR_ENV_GROUP_HOSTNAME es el nombre de host de tu grupo de entornos. Consulta Buscar el nombre de host de tu grupo de entornos.

Por ejemplo: 

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

Respuesta

Deberías ver la siguiente respuesta:

Hello, Guest!

Añadir una política de XML a JSON

A continuación, añadirás la política XML a JSON al flujo condicional Ver respuesta XML, que se generó automáticamente al crear el proxy de API a partir de la especificación de OpenAPI. La política convertirá la respuesta XML del objetivo en una respuesta JSON.

Primero, llama a la API para poder comparar los resultados con los que recibas después de añadir la política. En una ventana de terminal, ejecuta el siguiente comando cURL. Estás llamando al recurso /xml del servicio de destino, que devuelve de forma nativa un bloque de XML sencillo.

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

donde YOUR ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Buscar el nombre de host del grupo de entornos.

Respuesta

Deberías ver la siguiente respuesta:

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

Ahora vamos a convertir la respuesta XML en JSON. Añade la política XML a JSON al flujo condicional View XML Response del proxy de API.

Apigee en la consola de Cloud

  1. En la interfaz de usuario de Apigee, haz clic en la pestaña Desarrollar de la página Descripción general de la API de destino simulada.

    2. Selecciona Ver respuesta XML.

  2. En el panel de la izquierda, en Proxy Endpoints > default (Endpoints de proxy > predeterminado), haz clic en el flujo condicional View XML Response (Ver respuesta XML).
  3. En el panel de la izquierda, haga clic en el botón + de la fila Políticas.

  4. 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 de Nombre visible y Nombre.

  5. Haz clic en Crear para crear la política.

  6. Haz clic en el botón + situado junto al flujo Ver respuesta XML de la sección Respuesta.

    Selecciona + Paso.

  7. En el cuadro de diálogo Add Policy Step (Añadir paso de política), haz clic en el campo Select existing policy (Seleccionar política) y elige XML to JSON-1 (XML a JSON-1).

  8. Haz clic en Añadir. La política de XML a JSON se aplica a la respuesta.

    Política de XML a JSON en un flujo

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

  9. Haz clic en Guardar.

UI clásica de Apigee

  1. En la interfaz de usuario de Apigee, haz clic en la pestaña Desarrollar de la página Descripción general de la API de destino simulada.

    Pestaña Desarrollador

  2. En el panel de navegación de la izquierda, en Proxy Endpoints > default (Endpoints de proxy > predeterminado), haz clic en el flujo condicional View XML Response (Ver respuesta XML).

    Selecciona Ver respuesta XML.

  3. Haz clic en el botón + Paso de la parte inferior, que corresponde a la Respuesta del flujo.

    Selecciona + Paso.

    Se abrirá el cuadro de diálogo Añadir paso, que muestra una lista categorizada de todas las políticas que puedes añadir.

  4. Desplázate hasta la categoría Mediación y selecciona XML a JSON.

    Cuadro de diálogo Añadir paso
  5. Mantén los valores predeterminados de Nombre visible y Nombre.

  6. Haz clic en Añadir. La política de XML a JSON se aplica a la respuesta.

    Política de XML a JSON en un flujo
  7. Haz clic en Guardar.

Ahora que has añadido la política, vuelve a llamar a la API con cURL. Ten en cuenta que sigues llamando al mismo recurso /xml. El servicio de destino sigue devolviendo su bloque de XML, pero ahora la política del proxy de API convertirá la respuesta a JSON. Haz esta llamada:

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

donde YOUR ENV_GROUP_HOSTNAME es el nombre de host del grupo de entornos. Consulta Buscar el nombre de host del grupo de entornos.

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

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