Conceptos clave para Jitterbit API Manager

Esta página cubre los conceptos fundamentales que necesitas entender al trabajar con Jitterbit API Manager, incluyendo tipos de API, características de seguridad aplicadas a través de puertas de enlace de API, y la estructura de URL del servicio.

Tipos de API

Se pueden crear y publicar tres tipos de APIs en API Manager. Cada tipo interactúa con Harmony de manera única dentro de la arquitectura del sistema.

Para obtener más información sobre seguridad y arquitectura del sistema de Jitterbit, consulta Documento técnico de seguridad y arquitectura de Jitterbit.

API personalizada

Las APIs personalizadas exponen una operación de Harmony para su consumo. Para configurar una API personalizada, primero debes crear e implementar una operación en Harmony. La operación puede ser cualquier operación de Studio o Design Studio. Cuando configuras la API personalizada, haces referencia a la operación existente. Los consumidores de API llaman y consumen la operación a través de la API personalizada. Las APIs personalizadas se enrutan a través de agentes de Jitterbit (ya sean grupos de agentes en la nube o agentes privados).

Cómo funcionan las APIs personalizadas

Cuando un consumidor de API llama a una API personalizada, ocurre el siguiente proceso:

1. Un consumidor de API realiza una llamada a la API personalizada en la puerta de enlace de API en la nube.
2. La puerta de enlace de API en la nube autentica la solicitud y aplica políticas de seguridad. Luego enruta la solicitud de API personalizada al servicio de mensajería, que enruta solicitudes para grupos de agentes.
3. Un agente en la nube recibe la solicitud del servicio de mensajería.
4. El agente en la nube hace referencia a la operación de API personalizada que especificaste durante la configuración de API personalizada e inicia la operación implementada.
5. La operación responde con una carga útil de API. Esta carga útil es consistente con el tipo de respuesta que seleccionaste durante la configuración de API personalizada.
6. El agente en la nube enruta la carga útil de API de vuelta al consumidor de API.

Para obtener información sobre cómo configurar una API personalizada, consulta Configuración de API personalizada.

Servicio OData

Los servicios OData exponen una operación de entidad de API de Design Studio para su consumo. Para configurar un servicio OData, primero debes crear e implementar una operación de entidad de API en Harmony. Cuando configuras el servicio OData, haces referencia a la operación de entidad de API existente. Los consumidores de API llaman y consumen la operación a través del servicio OData. Los servicios OData se enrutan a través de agentes de Jitterbit (ya sean grupos de agentes en la nube o agentes privados).

Cómo funcionan los servicios OData

Cuando un consumidor de API llama a un servicio OData, ocurre el siguiente proceso:

1. Un consumidor de API realiza una llamada al servicio OData en la puerta de enlace de API privada.
2. La puerta de enlace de API privada autentica la solicitud y aplica políticas de seguridad. Luego enruta la solicitud del servicio OData.
3. El servicio de mensajería recibe la solicitud y enruta las solicitudes para grupos de agentes.
4. El agente privado recibe la solicitud del servicio de mensajería.
5. El agente privado hace referencia a la operación de entidad del servicio OData en Harmony e inicia la operación de entidad implementada.
6. El agente privado enruta la carga útil de API de la respuesta de la operación a través de la puerta de enlace de API privada de vuelta al consumidor de API.

Para obtener información sobre cómo configurar un servicio OData, consulta Configuración del servicio OData.

API de proxy

Las API de proxy funcionan con una API de terceros existente y no se enrutan a través de agentes de Jitterbit, a diferencia de las API personalizadas o los servicios OData que exponen una operación de Harmony para su consumo. La API que estás usando como proxy debe ser accesible para la puerta de enlace que procesa la API, ya sea la puerta de enlace de API en la nube o una puerta de enlace de API privada:

• Puerta de enlace de API en la nube: Si utilizas la puerta de enlace de API que Jitterbit aloja en Harmony, la API existente debe ser accesible públicamente, incluso si está protegida. La API que intentas usar como proxy no puede estar detrás de un firewall. Para incluir en la lista de permitidos las direcciones IP de la puerta de enlace de API en la nube y permitir que la puerta de enlace acceda a la API que estás usando como proxy, consulta Información de lista de permitidos y ve a https://services.jitterbit para tu región.

• Puerta de enlace de API privada: Si utilizas una puerta de enlace de API privada, la API existente debe ser accesible por la puerta de enlace de API privada.

Cómo funcionan las API de proxy

Cuando un consumidor de API llama a una API de proxy, ocurre el siguiente proceso:

1. Un consumidor de API realiza una llamada a la API de proxy en la puerta de enlace de API en la nube.
2. La puerta de enlace de API en la nube autentica la solicitud y aplica políticas de seguridad. Luego enruta la llamada de la API de proxy y la envía a la API de terceros que estás usando como proxy.
3. La API de terceros responde con una carga útil de API que se enruta a la puerta de enlace de API en la nube y de vuelta al consumidor de API.
4. El sistema envía información de estado en tiempo de ejecución a la base de datos de registros de transacciones.

Para obtener información sobre cómo configurar una API de proxy, consulta Configuración de la API de proxy.

Seguridad de API

Todas las solicitudes de API en Jitterbit API Manager deben pasar a través de puertas de enlace de API, que sirven como la capa principal de aplicación de seguridad para autenticación, autorización y control de acceso. API Manager proporciona múltiples características de seguridad que puedes configurar y administrar para varios casos de uso. Para obtener información sobre características de seguridad dentro de la arquitectura del sistema de Jitterbit, consulta Seguridad de Jitterbit.

Perfiles de seguridad

De forma predeterminada, una API es anónima y accesible públicamente cuando la creas, a menos que configures un perfil de seguridad en la página Perfiles de seguridad del Administrador de API y lo asignes a la API.

Un perfil de seguridad de API rige y asegura el consumo de API. Los perfiles de seguridad permiten que una API publicada sea consumida solo por un consumidor de API específico o un grupo de consumidores. Puedes crear y asignar perfiles de seguridad si eres miembro de la organización con permiso de Administrador.

Los administradores de la organización Harmony pueden requerir que asignes perfiles de seguridad a cada API cuando la creas mediante una configuración en las políticas de la organización Harmony.

Tipos de autenticación

Las opciones de autenticación en los perfiles de seguridad controlan el acceso a la API por parte de los consumidores de API. La siguiente tabla muestra los tipos de autenticación de perfil de seguridad disponibles:

Puertas de enlace de API como puntos de aplicación de seguridad

Tanto la puerta de enlace de API en la nube como las puertas de enlace de API privadas sirven como puntos de aplicación de seguridad en la arquitectura del Administrador de API. En estas puertas de enlace, el sistema realiza las siguientes acciones:

• Autentica consumidores de API usando el perfil de seguridad asignado
• Aplica limitación de velocidad y restricciones de dirección IP
• Aplica requisitos de cifrado SSL
• Registra todo el acceso a la API para auditoría de seguridad
• Bloquea solicitudes no autorizadas antes de que lleguen a los sistemas backend

Este modelo de seguridad garantiza una protección consistente en todos los tipos de API. También proporciona control centralizado sobre las políticas de acceso a la API.

Múltiples perfiles de seguridad

Se pueden usar múltiples perfiles de seguridad para emplear diferentes métodos de autenticación y opciones de seguridad en el mismo entorno, con cada perfil dirigido a un grupo específico de consumidores de API.

Por ejemplo, si se tienen dos tipos de consumidores (contabilidad y finanzas), y dos APIs (API-Revenue y API-Budget) en un entorno, y API-Revenue está destinada a consumidores de contabilidad y API-Budget está destinada a consumidores de contabilidad y finanzas, se puede crear un único perfil de seguridad para consumidores de contabilidad y asignarlo a ambas APIs. Luego se podría crear un perfil de seguridad separado para consumidores de finanzas y asignarlo a API-Budget.

El resultado de los dos perfiles de seguridad es que los consumidores de contabilidad (usando su perfil de seguridad) solo pueden acceder a API-Revenue, y los consumidores de finanzas (usando su perfil de seguridad separado) pueden acceder a API-Revenue o API-Budget.

Se permiten estas combinaciones de perfiles de seguridad:

• Se pueden asignar múltiples perfiles de seguridad con autenticación básica a una única API.
• Se pueden asignar múltiples perfiles de seguridad con autenticación de clave de API a una única API.
• Se puede asignar una combinación de perfiles de seguridad que usen autenticación básica y de clave de API a una única API.

No se permite ninguna otra combinación de perfiles de seguridad.

Límites de velocidad

Cada organización tiene dos asignaciones, según lo establecido en el acuerdo de licencia de Jitterbit de la organización. Los gateways de API aplican estos límites en el punto de entrada:

1. Asignación de llamadas de API por mes: La asignación total proporcionada a una organización en un mes. Todas las llamadas recibidas por todas las APIs (en todos los entornos) en un único mes cuentan hacia este límite.

2. Asignación de llamadas de API por minuto: La velocidad máxima a la que se puede consumir la asignación de una organización.

De forma predeterminada, un entorno o perfil de seguridad puede acceder a la asignación total de la organización para llamadas en todas las APIs dentro de un minuto.

Después de que una organización agota su asignación de llamadas por mes, todas las APIs dentro de la organización reciben una respuesta 429 Too Many Requests hasta que la asignación se restablezca a su asignación máxima el primer día del mes siguiente.

Se pueden usar límites de velocidad en el nivel de entorno y perfil de seguridad para aplicar un número máximo compartido de llamadas de API por minuto que se pueden realizar en todas las APIs dentro de un entorno al que se asigna un perfil de seguridad.

Además de los límites anteriores, el gateway de API en la nube administrado por Jitterbit aplica un límite a nivel de plataforma de 200 solicitudes de API por minuto por organización. Las solicitudes que superan este umbral se limitan por velocidad en la plataforma, que devuelve una respuesta 429 Too Many Requests. Este límite se aplica colectivamente en todos los tipos de API, incluidas APIs personalizadas, APIs proxy y solicitudes OData. Este límite no se aplica a gateways de API privados, donde el rendimiento se determina por la capacidad del servidor host.

Rangos de IP confiables

De forma predeterminada, un perfil de seguridad no limita el acceso a ningún rango de direcciones IP predeterminado. Se puede limitar el acceso a las APIs dentro de un perfil de seguridad a consumidores desde una única dirección IP o un rango de direcciones IP durante la configuración del perfil de seguridad.

Cuando un consumidor intenta acceder a una API con un perfil de seguridad limitado a una cierta dirección IP o rango, el gateway de API verifica la dirección IP del consumidor contra los rangos permitidos. Las direcciones IP que no cumplen los criterios se rechazan y se devuelve un mensaje Error 429.

Modo solo SSL

Se puede configurar cualquier API para usar encriptación SSL. Por defecto, todas las APIs admiten transferencia tanto HTTP como HTTPS.

La opción solo SSL permite redirigir el tráfico HTTP para garantizar que toda la comunicación esté encriptada. Symantec Class 3 Secure Server SHA256 SSL CA verifica la identidad de la URL HTTPS. La conexión a la URL HTTPS se encripta con criptografía moderna.

Se puede habilitar la opción solo SSL durante la configuración de una API personalizada, servicio OData, o API proxy.

Registros de API

Para cada solicitud a una API, se registra en un registro el perfil de seguridad utilizado para acceder a la API. La página Registros de API muestra una tabla de todos los registros de procesamiento de API y registros de depuración (si está habilitado el registro de depuración) para ayudar a editores y consumidores a solucionar problemas relacionados. Los registros se muestran para APIs personalizadas, servicios OData y APIs proxy cuando se llaman a través de la puerta de enlace de API en la nube o una puerta de enlace de API privada.

URLs de servicio de API

Se accede a las APIs personalizadas, servicios OData y APIs proxy creadas a través de Jitterbit API Manager utilizando la URL de servicio de una API. La URL de servicio es la URL que se utiliza para consumir la API usando el método de autenticación configurado.

Se puede llamar a la URL de servicio desde una aplicación. Si la API admite GET, se puede pegar la URL en un navegador web para consumir la API manualmente.

Formato de URL de servicio

Todas las URLs de servicio de API siguen el mismo formato. Las APIs proxy pueden tener parámetros de ruta de servicio adicionales:

<Protocol>://<Base URL>/<Environment URL Prefix>/<Version>/<Service Root>

<Protocol>://<Base URL>/<Environment URL Prefix>/<Version>/<Service Root>/<Service Path>

Componentes de URL de servicio

La URL de servicio de cada API se construye automáticamente con estas partes:

Solución de problemas

Para la solución de problemas relacionada, consulta lo siguiente en la guía de solución de problemas del Administrador de API:

• Error 429: Se superó la asignación mensual de llamadas a la API

• Límite de velocidad a nivel de plataforma: 200 solicitudes por minuto

• HTTP 504 Gateway Timeout