Configuración de API personalizada en Jitterbit API Manager

Introducción

Esta página describe cómo crear y configurar una API personalizada desde la página de APIs de Jitterbit API Manager. Las APIs personalizadas son uno de los tres tipos de APIs configurados a través del API Manager. Para los otros dos tipos — servicio OData y API proxy — consulte la configuración del servicio OData y la configuración de API proxy.

Alternativamente, las APIs personalizadas se pueden crear en Integration Studio utilizando la opción Publicar como API accesible desde el menú de acciones de una operación.

Las APIs personalizadas (publicadas y en borrador) se muestran en estas ubicaciones:

• La página de APIs del API Manager.
• La pestaña Recursos del panel del proyecto para el proyecto de Integration Studio asociado con la API personalizada.

Requisitos previos

Dado que una API personalizada expone una operación de Harmony para su consumo, primero debe crearse y desplegarse dicha operación en Harmony. La operación existente se referencia durante la configuración de la API personalizada. La operación que activa una API personalizada puede ser una operación de Integration Studio o de Design Studio.

Para obtener instrucciones sobre cómo crear y desplegar una operación, consulte estos recursos:

• Integration Studio
  • Creación y configuración de operaciones
  • Despliegue y ejecución de operaciones
• Design Studio
  • Creando una operación

Crear una nueva API personalizada

Cuando accedes a la página de APIs del Administrador de API, si no existen APIs personalizadas, servicios OData o APIs proxy en la organización seleccionada, esta pantalla está en blanco.

Para crear una nueva API personalizada, haz clic en Nuevo > API personalizada:

Al hacer clic en Nueva API, se abre la pantalla de configuración de la API personalizada. Los detalles sobre cómo configurar una nueva API personalizada se proporcionan en Configurar una API personalizada a continuación.

Configurar una API personalizada

La pantalla de configuración incluye cuatro pasos de configuración, cada uno cubierto a continuación:

• Paso 1: Configuración
• Paso 2: Seleccionar tipo de servicio y asignar operaciones
• Paso 3: Asignar roles de usuario y perfiles de seguridad
• Paso 4: Resumen y confirmación

La URL del servicio de una API es la URL utilizada para consumir la API usando un método de autenticación configurado. Las partes de la URL del servicio de una API se describen en Introducción al Administrador de API en URL del servicio de API.

La URL del servicio se muestra en la parte superior de cada paso después de completar el paso 1:

Paso 1: Configuración

• Nombre de la API: Ingresa un nombre para la API que se utilizará para fines de identificación interna. Se permiten estos caracteres especiales:

  ( ) - _

• Entorno: Utiliza el menú para seleccionar el entorno donde residirá la API. Puedes escribir cualquier parte del nombre del entorno en el menú para filtrar la lista de entornos. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

  Nota

  Después de la creación de la API, el entorno no se puede cambiar. Para mover una API entre entornos, puedes clonar la API o exportar e importar la API en otro entorno.

• Raíz del servicio: El nombre público de la API que se utilizará como parte de la URL del servicio de la API. Por defecto, este campo se completa con el nombre de la API convertido a camel case. Este campo no permite espacios ni ciertos caracteres especiales. No se recomienda utilizar caracteres especiales distintos de un guion bajo (_). Se permiten los siguientes caracteres especiales:

  . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -

• Versión: Ingresa una versión opcional para usar como parte de la URL del servicio de la API. Este campo permite un máximo de 48 caracteres y no permite espacios ni ciertos caracteres especiales. No se recomienda utilizar caracteres especiales distintos de un punto (.) o un guion (-). Las convenciones de nomenclatura comunes incluyen incrementar versiones, como v1.0, v1.1, v1.2, o usar una fecha en la que se publicó la API, como 2021-08-28.

• Descripción: Ingresa una descripción opcional para la API.

• Tiempo de espera: Ingresa el número de segundos antes de que la API se agote. El valor predeterminado es 30 segundos. El máximo es 180 segundos.

  Nota

  Esta configuración es independiente de la configuración de tiempo de espera de operación en Integration Studio o Design Studio. Las configuraciones de tiempo de espera de operación no se utilizan a menos que se use un agente privado y la configuración EnableAPITimeout en el archivo de configuración del agente privado esté habilitada.

• Solo SSL: Cuando se selecciona (por defecto), los datos se cifran a través de SSL y se aplica HTTPS para todas las solicitudes y respuestas de la API (recomendado).

  Cuando no se selecciona, los datos transmitidos a través de las solicitudes y respuestas de la API no están cifrados y pueden ser interceptados y vistos por otros. Esto podría exponer información sensible.

• Habilitar CORS: Seleccione para habilitar Intercambio de Recursos de Origen Cruzado (CORS) (no recomendado). Habilitar CORS está seleccionado por defecto.

  Advertencia

  Habilitar CORS hace que las operaciones que utilizan el método OPTIONS se ejecuten sin autenticación.

• Habilitar Registro Detallado: Seleccione para habilitar el registro detallado. El registro detallado para las APIs incluye datos de solicitud y respuesta en cada registro de API para ayudar a monitorear los datos entrantes y salientes y facilitar la depuración. Dado que esto puede crear archivos de registro grandes, el valor predeterminado es que el registro detallado está deshabilitado.

• Habilitar Modo de Depuración Hasta: Seleccione para habilitar el modo de depuración y habilitar la entrada de una fecha y hora correspondiente en la que se deshabilitará el modo de depuración. La duración máxima de habilitación es de dos semanas. El modo de depuración permite un seguimiento completo de cada solicitud recibida a través de la URL del servicio de la API. Cuando está habilitado, el sistema retiene el contenido completo de cada solicitud y respuesta de la API durante un máximo de 24 horas desde el momento en que se recibió la llamada a la API y se aplica a todas las operaciones desencadenadas por la API.

  Nota

  Navegar a través de los datos del evento puede volverse difícil con grandes volúmenes (pruebas de carga, pruebas en preproducción, etc.). El aumento en los datos retenidos puede resultar en preocupaciones de espacio de almacenamiento y seguridad. No recomendamos usar el modo de depuración en un entorno de producción.

• Siguiente: Haga clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso.

• Guardar cambios: Haga clic para guardar la configuración de este paso y navegar a Paso 4: Resumen y confirmación.

Paso 2: Seleccionar tipo de servicio y asignar operaciones

• Tipo de servicio: Seleccione API personalizada.

• Agregar servicio API: Haga clic para agregar un servicio API que exponga una operación de Harmony para su consumo. Una vez que se haga clic, se abrirá la configuración del servicio API individual (descrito a continuación). Se pueden agregar múltiples servicios API a una API personalizada.

Después de hacer clic en Agregar servicio API, se abre la configuración para un servicio API:

• Método de solicitud: Use el menú para seleccionar el método de solicitud para el servicio API, uno de GET, POST, PUT, DELETE, ALL o CUSTOM. Seleccionar ALL creará métodos separados GET, PUT, POST y DELETE para la Operación seleccionada (el método CUSTOM no está incluido). Por defecto, el método de solicitud está configurado como GET.

  Nota

  Los servicios API que utilizan un método CUSTOM no tendrán documentación OpenAPI generada a través del Portal Manager debido a una limitación de la especificación OpenAPI.

• Nombre del servicio: Ingrese un nombre para el servicio API.

• Ruta: Opcionalmente, ingrese una ruta para la solicitud. La ruta debe comenzar con una barra diagonal / y debe tener todos los parámetros de solicitud encerrados en llaves { }. No se permiten otros caracteres especiales.

  Nota

  La combinación de método de solicitud y Ruta debe ser única para cada servicio API en la API personalizada.

• Nombre del Método Personalizado: Visible cuando se selecciona CUSTOM como el método de solicitud. Ingrese el nombre del método que se utilizará, por ejemplo, PATCH. (Solo caracteres alfabéticos, guiones - y guiones bajos _.)

• Operación: Dentro de la pestaña Operación, se selecciona un proyecto y una operación para asignar al servicio API (requerido para habilitar el botón Guardar):

  • Asignar Proyecto: Utilice el menú para seleccionar un proyecto desplegado del entorno donde se está configurando la API (especificado en Paso 1: Configuración). Puede escribir cualquier parte del nombre del proyecto en el menú para filtrar la lista de proyectos. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

  • Editar Proyecto: Cuando se selecciona un proyecto de Integration Studio, este botón se habilita. Hacer clic en Editar Proyecto abre el proyecto en Integration Studio en una nueva pestaña.

    Nota

    Debe desplegar cualquier cambio realizado en el proyecto para que tenga efecto.

  • Asignar Operación(es): Utilice los menús para seleccionar una Operación y un Tipo de Respuesta para el servicio API:

    • Operación: Seleccione de las operaciones desplegadas en el proyecto seleccionado. Puede escribir cualquier parte del nombre de la operación en el menú para filtrar la lista de operaciones desplegadas. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla.

      Importante

      Por defecto, las operaciones exitosas configuradas para una API personalizada no se incluyen en los registros de operaciones a menos que se habilite una de estas configuraciones:

      • Agentes en la nube: Para operaciones API en un agente en la nube, se debe habilitar el registro de depuración de operaciones en la operación.
      • Agentes privados: Para operaciones API en un agente privado, se debe habilitar el registro de depuración de operaciones en la operación o debe establecer EnableLogging=true en la sección [APIOperation] del archivo de configuración del agente privado.

      Las operaciones no exitosas se incluyen en los registros de operaciones independientemente de si las configuraciones anteriores están habilitadas o no.

    • Tipo de Respuesta: Seleccione uno de Objetivo Final, Variable del Sistema o Sin Respuesta:

      • Objetivo Final: La respuesta de la API es el objetivo final de la cadena de operación. Cuando se selecciona este tipo de respuesta, la operación seleccionada debe tener, como objetivo final de la cadena de operación, una actividad de Respuesta de API de Integration Studio o una actividad de Escritura de Variable, o un objetivo de Respuesta de API de Design Studio o un objetivo de Variable Global. Si se utiliza cualquier otro objetivo final, la respuesta de la API estará vacía.

      • Variable del Sistema: La respuesta de la API se establece en una variable de Jitterbit en la cadena de operación. Cuando se selecciona este tipo de respuesta, la operación seleccionada debe tener, como parte de la cadena de operación, un script que establezca la variable de Jitterbit jitterbit.api.response igual a la respuesta que desea que la API devuelva. Si esta variable no se establece, la respuesta de la API estará vacía.

      • Sin Respuesta: La respuesta de la API está en blanco. Si se acepta la solicitud para ejecutar la operación seleccionada, la API devolverá una respuesta vacía inmediata con el código HTTP 202.

• Parámetros de ruta: Cuando se incluyen parámetros de solicitud en la Ruta, esta pestaña se completa con estos campos:

  

  • Parámetro: Muestra los parámetros de solicitud definidos en la Ruta.

  • Descripción: Opcionalmente, ingrese una descripción para los parámetros de solicitud.

• Parámetros de consulta: Esta pestaña permite agregar cualquier parámetro de consulta al servicio API:

  

  • Agregar parámetro: Haz clic para agregar un parámetro de consulta al servicio API. Una vez clicado, estos campos estarán disponibles:

    • Parámetro: Ingresa el nombre del parámetro de consulta.

    • Descripción: Opcionalmente, ingresa la descripción del parámetro de consulta.

    • Eliminar: Haz clic en el ícono de eliminar junto a un parámetro de consulta para eliminar ese parámetro.

• Encabezados: Esta pestaña permite agregar cualquier encabezado de solicitud al servicio API:

  

  • Agregar parámetro: Haz clic para agregar un encabezado de solicitud al servicio API. Una vez clicado, estos campos estarán disponibles:

    • Parámetro: Ingresa el nombre del encabezado de solicitud.

    • Descripción: Opcionalmente, ingresa la descripción del encabezado de solicitud.

    • Requerido: Selecciona si el encabezado de solicitud debe ser obligatorio para cada solicitud del servicio API.

    • Eliminar: Haz clic en el ícono de eliminar junto a un encabezado de solicitud para eliminar ese encabezado.

• Duplicar: Haz clic en el ícono de duplicar para crear un duplicado del servicio API.

  Nota

  Una vez que el servicio API se duplica, debes cambiar ya sea el método de solicitud o la Ruta, ya que cada servicio API debe tener una combinación única de esos campos.

• Eliminar: Haz clic en el ícono de eliminar junto a un servicio API para eliminarlo del API personalizado.

• Guardar: Haz clic para guardar el servicio API. Cuando la configuración de todos los servicios API esté completa, los botones Siguiente y Guardar cambios estarán habilitados. Una configuración de servicio API incompleta se indica con un ícono de error junto al nombre del servicio API:

  

Para resolver y habilitar los botones Siguiente y Guardar cambios, completa la configuración o elimina el servicio API.

• Cancelar: Haz clic para cancelar la configuración del servicio API.

• Siguiente: Haz clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso.

• Guardar cambios: Haz clic para guardar la configuración de este paso y navegar a Paso 4: Resumen y confirmación.

Paso 3: Asignar roles de usuario y perfiles de seguridad

• Asignar roles de usuario: Selecciona los roles de la organización cuyos miembros tendrán acceso a la API desde las páginas del Administrador de API que se enumeran a continuación. Los roles de los que se puede elegir son los definidos en la pestaña Roles de la página de Gestión de Usuarios.

  Esto determina el acceso a esta API específica desde estas páginas:

  • APIs
  • Administrador del Portal, incluida la generación de documentación de API
  • Portal
  • Registros de API
  • Analíticas

  El acceso a la página de Perfiles de Seguridad y el acceso para consumir la API no se ven afectados por esta selección. (El acceso para consumir una API está controlado por perfiles de seguridad.)

  Cualquier rol de usuario definido con el permiso Admin siempre tiene acceso completo a todas las APIs y, por lo tanto, no se puede deseleccionar. (En la captura de pantalla de ejemplo mostrada arriba, el rol Administrador no se puede deseleccionar por esa razón.)

  Nota

  Las APIs creadas antes de Harmony 10.22 tienen todos los roles de usuario seleccionados por defecto para asegurar el acceso continuo para todos los usuarios.

• Asignar Perfil(es) de Seguridad: Utiliza el menú desplegable para seleccionar un perfil de seguridad existente que se utilizará para restringir el acceso para el consumo de la API. Puedes escribir cualquier parte del nombre del perfil de seguridad en el menú para filtrar la lista de perfiles de seguridad. Los resultados del menú se filtran en tiempo real con cada pulsación de tecla. Puede ser necesario asignar un perfil de seguridad para guardar la API, dependiendo de las políticas de la organización de Harmony.

  • Asignar Perfil: Haz clic para asignar un perfil de seguridad seleccionado a la API. Los perfiles de seguridad asignados se enumeran en la tabla con el Nombre del Perfil y Tipo según lo configurado para el perfil de seguridad en configuración del perfil de seguridad. Si el Tipo es Básico, la columna Nombre de Usuario muestra el Nombre de Usuario proporcionado durante la configuración. Si el Tipo es cualquier otro tipo, la columna Nombre de Usuario muestra el mismo valor que el Tipo. Para eliminar un perfil asignado, haz clic en el ícono de eliminar .
  • Crear Nuevo Perfil: Haz clic para crear un nuevo perfil de seguridad. Para instrucciones, consulta Perfiles de Seguridad.

• Siguiente: Haz clic para almacenar temporalmente la configuración de este paso y continuar al siguiente paso. Si la API no tiene asignado un perfil de seguridad requerido, esta opción está deshabilitada.

• Guardar Cambios: Si está habilitado, haz clic para guardar la configuración de este paso. Si la API no tiene asignado un perfil de seguridad requerido, esta opción está deshabilitada.

• Saltar este Paso: Si está presente, haz clic para continuar al siguiente paso sin almacenar la configuración de este paso. Si la API no tiene asignado un perfil de seguridad requerido, esta opción no está presente.

Paso 4: Resumen y confirmación

• Nombre de la API y Entorno: El nombre de la API seguido del entorno entre paréntesis, según lo configurado en Paso 1: Configuración.

  • Descripción, Tiempo de espera, Solo SSL, CORS habilitado y Registro detallado habilitado: La descripción de la API y otras configuraciones que están habilitadas () o deshabilitadas (). Para realizar cambios en esas configuraciones, haga clic en el ícono de edición para regresar a Paso 1: Configuración.
  • Habilitar modo de depuración hasta: Esta opción es la misma que la descrita en Paso 1: Configuración. Puede cambiar esta configuración directamente desde este paso en lugar de tener que regresar al primer paso.

• Operaciones: Las operaciones asignadas en Paso 2: Seleccionar tipo de servicio y asignar operaciones con la información correspondiente para el tipo de servicio seleccionado. Para realizar cambios, haga clic en el ícono de edición para regresar a Paso 2: Seleccionar tipo de servicio y asignar operaciones.

• Roles de usuario y Perfiles de seguridad: Los roles y perfiles de seguridad asignados en Paso 3: Asignar roles de usuario y perfiles de seguridad. Para realizar cambios, haga clic en el ícono de edición para regresar a Paso 3: Asignar roles de usuario y perfiles de seguridad.

• Exportar: Genera e inicia la descarga de un archivo APK (apis-export.apk) que contiene una exportación de la API (ver Exportación e importación de APIs).

• Clonar: Crea una copia de una API existente. En la copia de la API, el Nombre de la API se precede con Copia de, la Raíz del servicio se precede con Copia de y la Versión se apenda con -2. La copia de la API se abre inmediatamente en su propio Paso 4: Resumen y confirmación.

• Eliminar: Elimina permanentemente la API y cierra la configuración. Un diálogo le pide que confirme que desea eliminar la API.

  Nota

  Si el estado de la API era Publicado o Publicado con Borrador en el momento de la eliminación, también se elimina del número de URLs de API utilizadas contra el límite de su suscripción. Si el estado de la API era Borrador en el momento de la eliminación, el número de URLs de API utilizadas contra su límite de suscripción no cambia, ya que la API no era accesible mientras estaba en estado de Borrador.

• Guardar como Borrador: Guarda la API en estado de Borrador o estado de Publicado con Borrador:

• Borrador: Una nueva API o una API cuyo estado era Borrador en el momento en que se utilizó Guardar como Borrador. Los borradores no cuentan contra su límite de suscripción de URLs de API.

• Publicado con Borrador: Una API cuyo estado era Publicado en el momento en que se utilizó Guardar como Borrador. Una API que se publica con un borrador cuenta contra su límite de suscripción de URLs de API, ya que la API es accesible aunque su borrador no lo sea.

• Guardar y Publicar: Guarda la API en estado de Publicado. La API está activa y accesible en cinco minutos. Una API publicada cuenta contra su límite de suscripción de URLs de API, ya que la API es accesible. Un diálogo indica que la API está activa:

  

• Copiar URL: Copia la URL del servicio de la API (ver URL del servicio de API).

• Generar Documento OpenAPI: Abre la página del Portal Manager, donde puedes generar documentación de la API para la página del Portal.
• Descartar: Cierra el diálogo.

Editar la API

Después de guardar la API, puedes editarla desde estas ubicaciones:

• Usando vista de mosaico en la página de APIs, haz clic en Ver/Editar.
• Usando vista de lista en la página de APIs, haz clic en Editar en la columna de Acciones.