Conceptos clave

Antes de aprender sobre la arquitectura e implementación de API Gateway, es importante comprender sus conceptos fundamentales en detalle.

API Gateway vs Security Rules

Catalyst API Gateway es una mejora de Catalyst Security Rules ya que proporciona funcionalidades adicionales para la gestión de APIs.

Puntos a recordar:

• Puedes habilitar o deshabilitar API Gateway en cualquier momento.
• Cuando API Gateway está deshabilitado, se seguirán por defecto las configuraciones definidas para una función de Catalyst en Security Rules.
• Cuando habilitas API Gateway para tu aplicación Catalyst, Security Rules se deshabilitará automáticamente.
• Después de habilitar API Gateway, las URLs de tus funciones y web client se volverán inmediatamente inaccesibles hasta que crees APIs para ellas. Por lo tanto, si habilitas API Gateway, debes crear APIs para todas tus funciones y web client.
• Puedes migrar las configuraciones de tus funciones en Security Rules a API Gateway usando auto-create.

Las diferencias entre Security Rules y API Gateway se especifican a continuación:

Enrutamiento

El propósito principal de un API Gateway es enrutar al cliente hacia los servicios apropiados. Esto se define por dos aspectos de una API: la solicitud y el destino. Si no se ha configurado una API para un método de solicitud o URL de solicitud en particular, el cliente no podrá acceder al destino.

Veamos estos conceptos en detalle.

Métodos de solicitud

Catalyst API Gateway admite los siguientes métodos de solicitud HTTP:

• GET
• PUT
• POST
• DELETE
• PATCH

También puedes agregar todos estos métodos HTTP bajo un método personalizado: ANY. Esto te permite crear una sola API para una función que admite los cinco métodos, en lugar de crear cinco APIs individuales, una para cada método. ANY se puede usar tanto en auto-create como en la creación de APIs personalizadas.

URL de solicitud

La URL de tu aplicación Catalyst tiene la siguiente estructura: https://project_domain_name.catalystserverless.com. Cuando creas una API, puedes definir la ruta de la solicitud y se agregará automáticamente a esta URL. Esta será la URL de solicitud.

Por ejemplo, si la ruta de la solicitud es /CustomerPortal/create, se agregará a la URL de la aplicación de ese proyecto, y se creará la siguiente URL de solicitud: https://shipmenttracking-61317105.catalystserverless.com/CusomerPortal/create.

Luego puedes proporcionar esta URL de solicitud intermediaria al cliente, en lugar de la URL predeterminada de la función de destino o del web client. La API enrutará automáticamente esta URL de solicitud al destino configurado.

Destino y URL de destino

Como se mencionó anteriormente, los componentes de destino de una API configurada en API Gateway pueden ser: Basic I/O functions, Advanced I/O functions, web client. Puedes establecer un destino para cada API que crees en API Gateway. Puedes crear múltiples APIs para cada destino para diferentes métodos de solicitud.

El formato de URL de cada destino es el siguiente:

• Basic I/O: https://project_domain_name.catalystserverless.com/baas/v1/ project/project_ID/function/function_ID/execute
• Advanced I/O: https://project_domain_name.catalystserverless.com/server/function_name/
• Web Client: https://project_domain_name.catalystserverless.com/app/

Puedes agregar rutas a la URL de destino de una función Advanced I/O o del web client y crear APIs para rutas específicas.

Uso de expresiones regulares (Regex) en la URL de solicitud y la URL de destino

Catalyst ofrece soporte para expresiones regulares para manejar valores dinámicos en la URL de solicitud. Una expresión regular (regex) es una secuencia de caracteres que describe un patrón de búsqueda. Cuando incluyes un patrón regex en la URL de solicitud, se ejecutan algoritmos de coincidencia de patrones y búsqueda y reemplazo cuando se proporciona el valor de entrada durante la ejecución y el patrón se reemplaza con el valor dinámico.

Puedes ingresar un patrón regex en formato JSON en la URL de solicitud y pasar la clave a la URL de destino de la siguiente manera:
Request url: /route/{path:[0-9]+}
Target url: /route/{path}

Por ejemplo, si el valor dinámico de una URL de solicitud contiene una cadena de números, puedes usar la expresión [0-9]+. Esto indica que los caracteres dentro de los corchetes en el valor dinámico pueden ser cualquier rango de números del 0 al 9 y el +* indica una o más ocurrencias de los dígitos. Por lo tanto, la URL de solicitud aquí podría configurarse como: /CustomerPortal/{portalID:[0-9]+}. Ahora, si agregas una ruta a la URL de destino de una función Advanced I/O como: /server/adIOFunc/CustomerPortal/{portalID}, el ID proporcionado por el usuario en la URL de solicitud al acceder a ella se pasará dinámicamente a la función Advanced I/O de destino.

También puedes usar un patrón comodín en tu expresión regular, como ., que indica que se puede aceptar cualquier número de caracteres literales o una cadena vacía en lugar del patrón comodín. Por ejemplo, si proporcionas un patrón comodín en la URL de solicitud como: /CustomerPortal/{path:(.*)}, el usuario podrá ingresar cualquier valor dinámicamente en la URL como: /CustomerPortal/johndoe12, /CustomerPortal/premiumUser/12809021, o /CustomerPortal/xae89013.

Si definiste un patrón regex en la URL para una función Advanced I/O en Security Rules, el mismo patrón se agregará tanto a la URL de solicitud como a la URL de destino durante auto-create.

Procesador de solicitudes de autenticación

El procesador de solicitudes maneja la autenticación de la API. La autenticación es una funcionalidad opcional en API Gateway. Si seleccionas No Authentication al crear la API, el destino será universalmente accesible para todos los clientes.

API Gateway admite tres métodos de autenticación. Puedes habilitar cualquiera de estos métodos o todos ellos.

API Key

Esta autenticación es manejada por una API key que Catalyst genera automáticamente para tu proyecto. La API Key es la misma para todos los proyectos en el entorno de desarrollo. Cuando despliegas un proyecto Catalyst al entorno de producción, Catalyst te proporcionará una API key diferente. Por lo tanto, tendrás API keys individuales para cada proyecto en el entorno de producción.

Puedes obtener la API key después de crear una API para una función Basic I/O o Advanced I/O en tu proyecto, con la opción de autenticación API Key habilitada. Haz clic en View API Key en la sección de detalles de la API para acceder a la clave.

Se abrirá una ventana emergente con la API key.

Puedes pasar la API key de dos maneras:

• Encabezado de solicitud
  Puedes pasar la API key como un encabezado en la URL de solicitud como se muestra en este ejemplo:
  

curl -X POST \
https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
-H "ZCFKEY: API_KEY"

• Query String
  También puedes pasar la API key como un parámetro de consulta en la URL de solicitud como se muestra en este ejemplo:
  

POST https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/
create?ZCFKEY=API_KEY

Reemplaza API_KEY con tu API key en ambos lugares.

Catalyst Users Authentication

Este método de autenticación habilita el acceso por defecto para todos los usuarios de tu aplicación Catalyst agregados en la sección Users de Catalyst Authentication. Puedes manejar este método de autenticación incorporando un formulario de inicio de sesión de usuario en tu aplicación Catalyst y habilitando una sesión de inicio de sesión. Los usuarios de la aplicación podrán acceder al destino de la API automáticamente sin necesidad de pasar por ninguna verificación de usuario adicional.

Autenticación basada en OAuth

Este método de autenticación habilita el acceso para los usuarios con un token de acceso OAuth.

Puedes pasar el token de acceso como un encabezado en la URL de solicitud como se muestra en este ejemplo:

curl -X POST \
https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
-H "Authorization: Zoho-oauthtoken Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57""

Para implementar la autenticación OAuth en tu aplicación Catalyst, consulta nuestra documentación de ayuda de autenticación OAuth para los pasos detallados.

Limitación de velocidad (Throttling)

La limitación de velocidad te permite establecer un límite de tasa para controlar el uso de una API por parte de los clientes. La limitación de velocidad es una funcionalidad opcional en Catalyst API Gateway. Cuando estableces límites de tasa de limitación de velocidad para una API, Catalyst monitoreará el conteo de solicitudes realizadas a esa API. Cuando las solicitudes enviadas excedan los límites que has configurado para la API, API Gateway devolverá la respuesta de error HTTP: 429 Too Many Requests.

Hay dos tipos de limitación de velocidad disponibles en API Gateway. Puedes usar uno o ambos métodos.

Limitación de velocidad general

La limitación de velocidad general define el máximo de solicitudes permitidas a la API para todos los usuarios, por unidad de tiempo. Puedes definir el límite de solicitudes, su tasa y la unidad de tiempo al crear la API.

Catalyst implementa un algoritmo de limitación de tasa de ventana deslizante donde la ventana comienza desde el elemento actual y se desplaza por un valor ponderado de la tasa de solicitudes de la ventana anterior. Por ejemplo, si estableces 50 solicitudes en 2 minutos como límite, Catalyst verificará las solicitudes a la API en los 2 minutos anteriores al segundo actual y determinará el conteo, en lugar de verificar en una ventana fija de 2 minutos.

Limitación de velocidad basada en IP

La limitación de velocidad basada en IP define el número máximo de solicitudes permitidas a la API desde una dirección IP en particular, por unidad de tiempo. Esto limita el número de llamadas a la API que se pueden realizar desde una dirección de cliente en particular. Puedes definir el límite de solicitudes, su tasa y la unidad de tiempo de manera similar a la limitación de velocidad general.

APIs auto-creadas, APIs personalizadas y la API predeterminada

Puedes crear APIs para tus funciones de Catalyst y web client de dos maneras: auto-create o personalizada.

Antes de hablar sobre las APIs auto-creadas y las APIs personalizadas, debes conocer la API predeterminada.

La API predeterminada

API Gateway crea una API predeterminada llamada Login Redirect para el web client alojado en tu proyecto Catalyst, además de la API regular del web client.

Las siguientes reglas se aplican para la API Login Redirect:

• Esta API se crea cuando creas APIs en API Gateway por primera vez después de alojar un web client en tu proyecto Catalyst, usando el método auto-create o el método personalizado.
• La API Login Redirect se crea basándose en la configuración establecida en el archivo client-package.json para el web client. La URL configurada como login_redirect en ese archivo se establecerá como la URL de solicitud y la URL de destino de la API. La clave login_redirect es opcional. Por lo tanto, si no está configurada, la URL proporcionada como homepage se establecerá como la URL de solicitud y la URL de destino.
• Si la URL configurada como login_redirect comienza con ‘/’, Catalyst la considerará como una ruta absoluta y la agregará directamente al dominio. Por ejemplo, si login_redirect es ‘/home.html’, la URL de solicitud tendrá el formato: https://project_domain_name.catalystserverless.com/home.html. Sin embargo, si el valor de login_redirect no comienza con ‘/’, como ‘home.html’, entonces la URL de solicitud tendrá el formato: https://project_domain_name.catalystserverless.com/app/home.html.
• Los valores de limitación de velocidad general y limitación de velocidad basada en IP para esta API predeterminada se establecerán en Not configured, y el valor de autenticación se establecerá en No authentication.
• Debes proporcionar la página predeterminada de redirección de inicio de sesión de la aplicación Catalyst como la URL de solicitud para la API Login Redirect. No debes proporcionar ninguna otra URL como su valor.
• Si cambias el valor de login_redirect en el archivo client-package.json después de que se creó la API Login Redirect, el valor de la URL de destino se cambiará automáticamente cuando despliegues el paquete del cliente en la consola de Catalyst.
• No podrás editar ninguno de estos valores predeterminados excepto la URL de solicitud. No podrás modificar la URL de destino, el nombre de la API, la autenticación o los parámetros de limitación de velocidad.
• No podrás eliminar la API Login Redirect.
• La diferencia entre la API predeterminada Login Redirect y las APIs regulares del web client es que la Login Redirect API está destinada únicamente a la página predeterminada de redirección de inicio de sesión de la aplicación a la que los usuarios son redirigidos después de iniciar sesión. Sin embargo, puedes agregar rutas a la URL de destino de un web client y crear APIs para diferentes rutas para las APIs regulares del web client.
• Si no has alojado un web client en tu proyecto Catalyst, esta API no se creará.

APIs auto-creadas

Puedes habilitar a Catalyst para crear automáticamente APIs para las funciones que elijas, o para el web client, usando el método auto-create. La creación automática de APIs solo está disponible hasta que crees tu primera API en API Gateway.

Auto-create se puede usar cuando tienes un gran número de funciones configuradas en tu proyecto Catalyst, y crear APIs individuales para cada una de ellas sería muy lento.

Cuando usas auto-create para crear APIs, se siguen estos protocolos:

• Si has configurado definiciones para tus funciones en Security Rules, se migrarán a API Gateway automáticamente durante auto-create. Si no has configurado ninguna definición, se aplicarán las reglas predeterminadas.
• Las APIs creadas para una función durante auto-create contendrán los métodos HTTP y la autenticación configurados en Security Rules.
• Métodos de solicitud y URL:
  
  • Si los cinco métodos HTTP (GET, PUT, POST, DELETE, PATCH) están habilitados para una función en Security Rules, se creará automáticamente una sola API con el método de solicitud ‘ANY’ para la función.
  • Si uno o más de los cinco métodos HTTP está deshabilitado para una función en Security Rules, se crearán APIs individuales para cada uno de los otros métodos.
  • La URL de solicitud de una función será la misma que su URL de destino predeterminada o la URL de la función en auto-create, ya que la URL de solicitud y la URL de destino son las mismas en Security Rules.
  • Si hay un patrón regex en la URL de solicitud de una función, el mismo patrón se asignará a la URL de destino.
• Autenticación:
  
  • Si el método de autenticación para una función en Security Rules es optional, el procesador de solicitudes se establecerá automáticamente en No Authentication para las APIs de la función durante auto-create.
  • Si la autenticación para una función en Security Rules está habilitada, Catalyst Users Authentication y OAuth-based Authentication se habilitarán automáticamente para las APIs de la función en API Gateway.
• Limitación de velocidad: Los valores de limitación de velocidad general y limitación de velocidad basada en IP para las APIs de una función se establecerán en Not configured por defecto durante auto-create.
• Nombre de la API: Una API creada usando auto-create para una función se nombrará en el formato: FunctionName_HTTPMethod. Una API creada para un web client usando auto-create se nombrará en el formato: WebclientName.
• API del web client: Los valores de limitación de velocidad general y limitación de velocidad basada en IP para un web client se establecerán en Not configured. Como se mencionó anteriormente, la autenticación no está disponible para las APIs del web client. La URL de solicitud de un web client también será la misma que su URL de la aplicación web de destino.
• Límites estrictos: El límite estricto para el número de APIs que se pueden crear es 1000 APIs/proyecto.

Después de que se creen las APIs para tus funciones y web client usando auto-create, puedes editar las APIs individuales y modificar los valores predeterminados según sea necesario.

API personalizada

Puedes crear una API personalizada para tu función o web client en cualquier momento y configurar los parámetros de la API. Puedes definir el método de solicitud y la URL, el destino, los métodos de autenticación, la limitación de velocidad y más según tus requisitos. La creación de una API personalizada no migra las configuraciones de una función desde Security Rules.