Desarrollar un proxy de APIs sencillo

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

Consulta la documentación de Apigee Edge.

Apigee te permite exponer rápidamente servicios de backend como APIs. Para ello, crea un proxy de API que proporcione una fachada para el servicio de backend que quieras exponer. Solo tienes que proporcionar la dirección de red del servicio de backend, junto con información que Apigee utiliza para crear el proxy de API que se expone a los desarrolladores.

El proxy de API desvincula la implementación del servicio de backend de la API que consumen los desarrolladores. De esta forma, los desarrolladores no se verán afectados por los cambios que se produzcan en el futuro en tus servicios de backend. Cuando actualizas los servicios de backend, los desarrolladores, que no se ven afectados por esos cambios, pueden seguir llamando a la API sin interrupciones.

En este tema se ofrece información sobre los distintos tipos de proxies y sus ajustes. Para obtener instrucciones detalladas sobre cómo crear proxies, consulta los siguientes temas:

Crear un proxy de API con la interfaz de usuario

La forma más sencilla de crear un proxy de API es usar el asistente Crear proxy.

Interfaz de 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. Haz clic en + Crear.

Interfaz clásica

Para acceder al asistente Crear proxy mediante la interfaz de usuario de Apigee, sigue estos pasos:

  1. Inicia sesión en la interfaz de usuario de Apigee.
  2. En la barra de navegación, selecciona Desarrollar > Proxies de API.
  3. Haz clic en Crear.
    Botón Crear proxy

Se muestra el asistente Crear proxy, que te guía por los pasos para generar y añadir funciones mínimas a un proxy de API.

La primera página del asistente te permite crear un proxy de API a partir de las siguientes fuentes:

Tipo Descripción
Proxy inverso (la más habitual)

Un proxy de API que dirige las solicitudes entrantes a los servicios de backend HTTP. Puede ser una API JSON o XML. Consulta la sección Crear un proxy inverso para un servicio HTTP más adelante en este artículo.

Haz clic en Usar especificación de OpenAPI para generar el proxy a partir de una especificación de OpenAPI válida. Para obtener más información sobre esta opción, consulta la sección Usar especificaciones de OpenAPI para generar proxies más adelante en esta sección.

Sin objetivo

Un proxy de API sin backend de API ("sin destino"). Es similar a crear un proxy inverso para un servicio HTTP, que se ha descrito anteriormente, pero no especificarás una API cuando definas los detalles del proxy de API.

Haz clic en Usar especificación de OpenAPI para generar el proxy a partir de una especificación de OpenAPI válida. Para obtener más información sobre esta opción, consulta la sección Usar especificaciones de OpenAPI para generar proxies más adelante en esta sección.

Subir paquete de proxy Un paquete de proxy de API (por ejemplo, uno de los proxies de API de ejemplo disponibles en GitHub). Consulta Importar un proxy de API desde un paquete de proxy de API.
Proxy con eventos enviados por el servidor (SSE) Un proxy de API que incluye un EventFlow para transmitir eventos enviados por el servidor (SSE). Para obtener más información, consulta Transmitir eventos enviados por el servidor.

En las siguientes secciones se explican los detalles de cada tipo de proxy.

Crear un proxy inverso para un servicio HTTP

Apigee genera proxies inversos a partir de la siguiente información:

  • URL del servicio de backend.
  • Ruta de URI que identifica de forma única la API que expondrá el proxy de API a las aplicaciones de consumidor.

La URL del servicio backend suele representar una aplicación habilitada para servicios propiedad de tu organización. También puede apuntar a una API disponible públicamente. La API o el servicio pueden estar bajo tu control (por ejemplo, una aplicación interna de recursos humanos o una aplicación Rails en la nube) o pueden ser una API o un servicio de terceros (por ejemplo, Twitter o Instagram).

Los siguientes detalles del proxy están disponibles después de acceder al asistente para crear proxy y seleccionar un tipo de proxy:

Campo Descripción
Nombre Nombre que se muestra de tu API. Especifica caracteres alfanuméricos, guiones (-) o guiones bajos (_).
Ruta base

Fragmento de URI que aparece después de la dirección http://[host] o https://[host] de tu proxy de API. Apigee usa el URI de la ruta base para buscar y enrutar los mensajes de solicitud entrantes al proxy de API adecuado.

Después de la ruta base, se incluyen las URLs de recursos adicionales. La estructura completa de la URL que usan los clientes para llamar a tu proxy de API es la siguiente:

https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH

Usar comodines en rutas base

Usa uno o varios comodines /*/ en las rutas base de los proxies de API para que estos no queden obsoletos. Por ejemplo, una ruta base de /team/*/members permite que los clientes llamen a https://[host]/team/blue/members y https://[host]/team/green/members sin que tengas que crear nuevos proxies de API para admitir nuevos equipos. Ten en cuenta que /**/ no es compatible.

Descripción (Opcional) Descripción de la API.
Destino (API actual) URL del servicio de backend que invoca este proxy de API.

Importar un proxy de API desde un paquete de proxy de API

A menudo, las defines como una colección de archivos XML, junto con otros archivos auxiliares. Si defines tus proxies de API como un conjunto de archivos externos a Apigee, podrás mantenerlos en un sistema de control de versiones y, a continuación, importarlos a Apigee para probarlos y desplegarlos.

Para importar proxies de API desde un paquete de proxies de API, sigue estos pasos:

  1. Accede al asistente Crear proxy como se describe en Crear un proxy de API con la interfaz de usuario.
  2. Especifica los detalles del paquete del proxy de API.
  3. Interfaz de Apigee en la consola de Cloud

    1. En el menú Plantilla de proxy, selecciona Subir paquete de proxy.
    2. En la sección Detalles del proxy, introduce el Nombre del proxy, sube el archivo ZIP y haz clic en Siguiente.
    3. En la sección Implementar, seleccione los entornos de implementación que quiera y haga clic en Crear.

    Interfaz clásica

    1. Haz clic en Subir paquete proxy.
    2. En la página Subir paquete proxy del asistente para proxies, introduce la siguiente información:

      Campo Descripción
      Paquete ZIP Archivo ZIP que contiene la configuración del proxy de API. Arrastra y suelta el archivo o haz clic para ir a él.
      Nombre Nombre que se muestra de tu API. El valor predeterminado es el nombre del archivo ZIP sin la extensión.
    3. Haz clic en Siguiente.
    4. En la página Resumen, selecciona los entornos de implementación que quieras y haz clic en Crear e implementar.

      Se muestra una confirmación que indica que se ha creado correctamente el nuevo proxy de API.

    5. Haz clic en Editar proxy para mostrar la página de detalles del proxy de API.

Crear proxies de API gRPC

Además de los proxies de API REST, Apigee admite proxies de API gRPC solo con compatibilidad de transferencia por el momento. Con la compatibilidad con el paso directo, la carga útil de gRPC es opaca para Apigee y el tráfico se enruta desde el cliente de gRPC al servidor de destino de gRPC preconfigurado en la configuración de destino.

Por el momento, los proxies de API gRPC de Apigee:

  • Admite solicitudes gRPC unarias.
  • No se pueden usar políticas que afecten a la carga útil.
  • Se puede usar en productos de API que no estén asociados a proxies GraphQL o REST. Las cuotas específicas de productos de la API y otros ajustes de operaciones se aplican a todos los proxies del producto.
  • No se admiten en Apigee Hybrid.
  • Usa dos variables de flujo específicas de gRPC: request.grpc.rpc.name y request.grpc.service.name.
  • Se puede monitorizar con estas variables de analíticas de Apigee específicas de gRPC: x_apigee_grpc_rpc_name, x_apigee_grpc_service_name y x_apigee_grpc_status.
  • Devuelve códigos de estado de gRPC.

También debes configurar el balanceador de carga para que admita gRPC. Consulta Usar gRPC con tus aplicaciones y Usar comandos de la CLI de gcloud para crear rutas de gRPC.

Para crear un proxy de API gRPC, primero define un servidor de destino gRPC (consulta Crear TargetServers) y, a continuación, especifica ese servidor de destino al crear el nuevo proxy.

Usar comandos de la CLI de gcloud para crear rutas de gRPC

En esta sección se muestran comandos de ejemplo para crear rutas de proxies gRPC mediante la CLI de gcloud. Las instrucciones incluyen la configuración de balanceadores de carga, un servidor de destino y un MIG.

Esta sección no es una guía completa para crear el enrutamiento. Puede que estos ejemplos no sean adecuados para todos los casos prácticos. Además, estas instrucciones presuponen que conoces el enrutamiento externo (MIG) y la configuración de gRPC de balanceadores de carga en la nube.

Definir variables de entorno

Estas variables de entorno se usan en los comandos de las subsecciones.

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Añadir seguridad

La seguridad del proxy se consigue añadiendo una política al proxy. Para obtener más información sobre las políticas, consulta ¿Qué es una política? Para obtener más información sobre la seguridad, consulta Proteger un proxy.

Para añadir una política de seguridad a tu proxy, sigue estos pasos:

Apigee en la consola de Cloud

  1. Crea un proxy como se describe en Crear un proxy de APIs.
  2. Añade una política de seguridad tal como se describe en una de las secciones de Proteger un proxy. Las políticas de seguridad más habituales son las claves de API y OAuth2.

UI clásica de Apigee

En la página Common policies (Políticas comunes) del asistente Create Proxy (Crear proxy), seleccione el tipo de autorización de seguridad que quiera añadir. En la siguiente tabla se resumen las opciones disponibles:

Autorización de seguridad Descripción
Clave de API Añade una verificación sencilla de la clave de API al proxy de API que estás definiendo. En respuesta, la API Platform añade una política VerifyAPIKey y una política AssignMessage a tu proxy de API. La política VerifyAPIKey valida las claves de API que presentan las aplicaciones que realizan solicitudes. La política AssignMessage elimina la clave de API, proporcionada en la llamada a la API como parámetro de consulta, de la solicitud reenviada al servidor backend.
OAuth 2.0 Añade la autenticación basada en OAuth 2.0 a tu proxy de API. Apigee añade automáticamente las siguientes políticas a tu proxy de API: una política para verificar un token de acceso y otra política para eliminar el token de acceso del mensaje antes de reenviarlo a tu servicio backend. Para saber cómo obtener un token de acceso, consulta OAuth.
Pasar a un gesto del sistema (sin autorización) No se requiere autorización. Las solicitudes se transfieren al backend sin que Apigee realice ninguna comprobación de seguridad.

Añadir compatibilidad con CORS

El uso compartido de recursos entre dominios (CORS) es un mecanismo estándar que permite a un navegador web hacer solicitudes directas a otro dominio. El estándar CORS define un conjunto de encabezados HTTP que los navegadores y servidores web usan para implementar la comunicación entre dominios.

Para añadir compatibilidad con CORS, añade la política de CORS al PreFlow de la solicitud del ProxyEndpoint.

Para obtener información más detallada sobre la compatibilidad con CORS, incluido cómo añadir compatibilidad con solicitudes preparatorias de CORS a un proxy, consulta el artículo Añadir compatibilidad con CORS a un proxy de API.

Añadir cuotas

Las cuotas protegen tu servicio de backend frente a un tráfico elevado en Quota. Consulta Cuotas. Esta opción no está disponible si se selecciona la autorización de transferencia.

Usar especificaciones de OpenAPI para generar proxies

En esta sección se describe la opción Usar OpenAPI, que está disponible para generar los siguientes tipos de proxies de API a partir de una especificación de OpenAPI: inversos o sin destino.

¿Qué es una especificación de OpenAPI?

Logotipo de Open API Initiative   "La iniciativa Open API (OAI) se centra en crear, desarrollar y promover un formato de descripción de APIs independiente del proveedor basado en la especificación de Swagger". Para obtener más información, consulta la iniciativa 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 la 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 APIs.

El siguiente fragmento de una especificación de OpenAPI describe el servicio de destino simulado de Apigee, http://mocktarget.apigee.net. Para obtener más información, consulta la especificación de OpenAPI del ejemplo helloworld.

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
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Con el asistente Crear proxy, puedes importar una especificación de OpenAPI y usarla para generar un proxy de API. Una vez generado el proxy, puedes usar la interfaz de usuario de Apigee para seguir desarrollándolo. Para ello, añade políticas, implementa código personalizado, etc., como con cualquier otro proxy de Apigee.

Crear un proxy de APIs a partir de una especificación de OpenAPI

Crea tus proxies de API a partir de una especificación de OpenAPI. Con solo unos clics, tendrás un proxy de API con las rutas, los parámetros, los flujos condicionales y los endpoints de destino generados automáticamente. Después, puedes añadir funciones como seguridad de OAuth, limitación de frecuencia y almacenamiento en caché.

En el asistente Crear proxy, haz clic en Usar especificación de OpenAPI y sigue los pasos para crear un proxy de destino inverso o sin destino a partir de una especificación de OpenAPI. Para obtener más información, consulta el artículo Crear un proxy de APIs a partir de una especificación de OpenAPI.

Crear una revisión de un proxy de API

Para crear una revisión de un proxy de API, sigue estos pasos:

  1. Abre la interfaz de usuario de Apigee.
  2. Apigee en la consola de Cloud

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

    Ir a proxies de API

    UI clásica de Apigee

    1. Inicia sesión en la interfaz de usuario de Apigee.
    2. En la barra de navegación, selecciona Desarrollar > Proxies de API.
  3. En la lista, haz clic en el proxy de API que quieras copiar.
  4. Haz clic en la pestaña Desarrollar.

  5. Seleccione el botón Guardar y, a continuación, Guardar como nueva revisión.

Crear una copia de seguridad de un proxy de API

Puedes crear una copia de seguridad de un proxy de API como un conjunto de archivos XML en un paquete de proxy de API. Una vez que se haya exportado a un paquete, puedes importar el proxy de API a un nuevo proxy, tal como se describe en la sección Importar un proxy de API desde un paquete de proxy de API de este artículo. Para obtener más información, consulta Descargar proxies de APIs.

Crear un proxy de API con la API

Para crear un proxy de API mediante la API, consulta Crear un proxy de API.

Acerca de la ausencia de proxies de destino

Los proxies de destino de Apigee son útiles cuando quieres procesar solicitudes en Apigee sin reenviarlas a un servicio de backend. Es importante saber cuándo es adecuado este enfoque.

Casos prácticos habituales

  • Interactuar con datos gestionados por Apigee: un proxy sin destino es útil en los casos en los que solo necesitas interactuar con datos gestionados por Apigee, como los datos almacenados en un mapa de clave-valor (KVM) o en la caché de Apigee. Por ejemplo, puedes usar un proxy sin destino para recuperar datos de la KVM, como datos de sesión de usuario o datos de configuración. En este caso, no es necesario llamar a un servicio backend. Solo necesitas una política KeyValueMapOperations en el flujo del proxy. Por ejemplo, puede que quieras que la persona que llama solicite que se vacíe la caché. Para ello, puedes invocar la política InvalidateCache sin necesidad de conectarte a ningún destino.
  • Usar APIs simuladas: puedes crear APIs simuladas para simular el comportamiento de las APIs antes de que se complete la implementación del backend, lo que permite que el desarrollo del frontend avance de forma independiente. Para obtener más información sobre cómo crear APIs simuladas, consulta Proxy de API simulada de OpenAPI.
  • Gestión de tokens: Apigee puede emitir tokens OAuthV2, lo que suele hacerse a través de un proxy sin destino.
  • Probar el comportamiento de las políticas: un proxy sin destino puede ser útil cuando quieras probar las políticas de Apigee para comprobar su comportamiento.