Crear, Editar y Eliminar APIs

Creación de una API

Para crear una nueva API manualmente, haga clic en el botón + Create API, ubicado en la esquina superior derecha de la pantalla API Catalog. Se abrirá un menú con las siguientes opciones para la creación de APIs:

api home

  • Create API: permite crear una API REST desde la interfaz de API Management introduciendo todos los datos manualmente.

  • Create Identity: permite crear una API Identity introduciendo manualmente los datos requeridos.

  • Create GraphQL: permite crear una API GraphQL introduciendo manualmente los datos requeridos.

  • Import an API: permite crear una API importando un archivo de documentación en formato JSON o YAML. Consulte más información sobre la importación y las versiones de especificación aceptadas a continuación.

  • Create API with AI (beta): crea una nueva API REST con la ayuda de inteligencia artificial. Consulta la guía completa de esta opción.

Para que la opción Create API with AI (beta) esté disponible en su entorno, solicite su habilitación al equipo de producto a través del canal de soporte.

Al hacer clic en Create API, se debe seleccionar, en la ventana modal que se abrirá, qué especificación debe seguir la API: Swagger 2.0 u OpenAPI 3.0. La versión de la especificación seleccionada será mantenida internamente por el sistema.

Después de elegir una de las opciones anteriores, se mostrará la pantalla de registro y se deberán rellenar los campos requeridos (a menos que decida importar un archivo Swagger, que ya crea la API, con la posibilidad de editar los campos).

  • Los campos API Name y Description no aceptan los caracteres '<' y/o '>'.

  • En el campo Base path, debe incluir la ruta base de la API. Formará parte de la URL de acceso a la API (que se complementará con la dirección de entrada y el entorno de despliegue). Aparte de las letras y los números, estos son los caracteres aceptados para la ruta:

    • Fuera de las llaves: ! @ $ & ( ) - _ = ' ; : ~ +

    • Dentro de las llaves (parámetro de la ruta): - _

Consulte también:

Si un entorno ya está registrado en Environments, se muestra la opción Deployable Environments. De lo contrario, el entorno se puede agregar más adelante.

Lea más sobre Environments.

La opción Access token expires in determina el período de tiempo de caducidad de tokens para una API determinada. Si no establece un valor, el tiempo por defecto de 3600 segundos se tendrá en cuenta.

La opción Context está relacionada con la visibilidad de su API, que solo se mostrará a los usuarios autorizados. Las opciones son:

  • Organization: la API será visible para todos los usuarios que hayan iniciado sesión en el sistema;

  • Teams: la API será visible para los usuarios miembros del equipo seleccionado.

    Lea más sobre la creación de equipos aquí;

  • Only me: la API será visible sólo para el usuario que la creó;

  • Add users: la API también será visible para los usuarios agregados, como se muestra en la siguiente imagen:

Para configurar correctamente las opciones de visibilidad de su API, los usuarios y equipos deben estar ya registrados. Vea la documentación de Access Control para más información sobre la creación de usuarios y los roles de acceso.

La opción Private API, cuando está activada, no permite que la API esté disponible para su consumo en el Portal de Desarrolladores.

Al hacer clic en Save and next, se guardarán los datos básicos de la API. Los dos pasos siguientes (Resources y Flows) no son obligatorios (sin embargo, si la importación de un Swagger se había realizado anteriormente, los datos de recursos ya se completarán). Para más detalles, acceda a las páginas sobre Resources y Flows.

El último paso para crear la API es la pantalla Publish:

create api publish

Es posible realizar el despliegue de la API en un entorno si la opción Environments fue seleccionada al inicio del registro. También puede crear plantillas de prueba, que generarán un plan y una aplicación vinculados a la API registrada. Esta opción le permitirá usar su API inmediatamente.

Una vez registradas, las APIs se organizan en cards.

card api

Edición de una API

Para acceder a la pantalla de edición de la API, haga clic en el card. Será dirigido a la pantalla Overview.

Para editar la información de la API, haga clic en Edit API, ubicado en la esquina superior derecha de la pantalla.

edit api

La pantalla Overview está destinada exclusivamente a la visualización de la información. Cualquier cambio en la API solo puede realizarse en la pantalla Edit API.

Para más información, consulte la documentación de la pantalla Overview.

Información general

En la parte superior de la pantalla Edit API se muestran la información general de la API y las principales acciones del flujo de edición.

general information

En esta área es posible:

  • visualizar el Name de la API, el Type (REST o GraphQL) y si la API es Identity.

  • consultar la cantidad de Apps asociadas y la Revision seleccionada.

  • habilitar el editor de Swagger.

  • acceder a API Trace.

  • consultar la fecha de creación de la API.

  • visualizar los planes asociados, cuando existan.

Acciones de guardado

En el área de información general también están disponibles las acciones:

  • Save: Guarda todos los cambios realizados en todas las pestañas de la API. El guardado no se limita a la pestaña activa; la API se guarda como un todo.

  • Save as new revision: guarda los cambios creando una nueva Revision de la API.

  • Cualquier cambio solo se aplica después de hacer clic en Save.

  • Excepción: las acciones de Deploy y Undeploy se ejecutan inmediatamente, independientemente del botón Save.

Menú de acciones

Junto al botón Save está disponible el menú de acciones (botón de más opciones ⋮), que reúne operaciones de la API como creación de nueva versión, clonación, exportación y eliminación.

acoes edit api

Para eliminar una API, es obligatorio escribir delete para confirmar la acción.

Pestañas de navegación

API Definitions

La pestaña API Definitions permite configurar las definiciones básicas de la API, como identificación, alcance organizacional (contexto, organización y equipos) y opciones de exposición en el Portal.

El campo Description permite ajustar el tamaño del área de edición. Utilice el control en la esquina inferior derecha del campo para ampliar o reducir el espacio de escritura.

La funcionalidad API Portal Settings en esta pestaña permite configurar la visibilidad y disponibilidad de la API en el Portal de Desarrolladores. Las opciones disponibles son:

  • Allow Apps link: cuando está activada, la API queda disponible en la sección Register New App del Portal de Desarrolladores. De lo contrario, la API no podrá ser consumida por apps.

  • Show iterative documentation (Swagger): cuando está activada, la API queda disponible para pruebas en el Portal de Desarrolladores. Utiliza el botón Add try it out environments para seleccionar los entornos de prueba y la revisión que se aplicará.

Las configuraciones disponibles en API Portal Settings se aplican únicamente a Portales basados en la stack Drupal.

En el nuevo Portal de Desarrolladores basado en Strapi, estas configuraciones aparecen directamente en el Portal Manager.

Los cambios realizados en esta pestaña solo se aplican después de hacer clic en Save.

Resources

La pestaña Resources permite editar los recursos y operaciones de la API.

Cuando existen recursos registrados, cada elemento de la lista muestra un menú de acciones (botón de más opciones ⋮).

Desde este menú es posible:

  • a nivel de Resource:

    • agregar una nueva operación

    • editar el recurso

    • eliminar el recurso

  • a nivel de Operación:

    • editar la operación

    • eliminar la operación

Los cambios realizados en esta pestaña solo se aplican después de hacer clic en Save.

Flows

La pestaña Flows permite editar los interceptores aplicados a los recursos y operaciones de la API.

flows edit

El flujo se abre directamente en modo de edición.

Durante la edición es posible:

  • configurar y ajustar los interceptores del flujo;

  • utilizar el botón Reset Operation, disponible directamente en el Flow;

  • visualizar un tooltip al pasar el cursor sobre el botón Reset Operation;

  • confirmar la acción de reset mediante un modal de confirmación;

  • definir el destino de la solicitud mediante la opción Set API Destination.

  • El reset de la operación solo se aplica después de hacer clic en Save.

  • Al cancelar la edición, no se aplica ningún reset al Flow.

Environments

La pestaña Environments permite editar los entornos en los que la API está desplegada.

environments edit

En esta pestaña es posible:

  • agregar un nuevo environment a la API mediante la opción Add Environment.

  • ejecutar acciones de Deploy y Undeploy, que se realizan inmediatamente tras la confirmación, de forma independiente del botón Save.

  • confirmar la acción al cambiar el estado del switch de Deploy.

  • copiar la URL del environment utilizando el botón de Copy disponible.

  • eliminar environments directamente desde esta pantalla mediante el botón de Delete.

  • Las acciones de Deploy y Undeploy no dependen del botón Save.

  • El modal de Add Environment es el único flujo en el que una acción ejecuta el guardado automático de la API.

  • La eliminación de environments solo puede realizarse en la pantalla Edit API.

Timeline

La pestaña Timeline muestra los cambios realizados en la API, con filtros por período y tipo de cambio.

Eliminación de una API

Para eliminar una API, utilice la opción Delete API disponible en el menú de acciones (botón de más opciones ⋮) ubicado en la esquina superior derecha de la pantalla.

Para confirmar la eliminación, es obligatorio escribir delete.

Importación de APIs

Puede crear APIs a partir de la importación de archivos de documentación que siguen la especificación OpenAPI. Las versiones admitidas de la especificación son: Swagger 2.0 u OpenAPI 3.0.

Para esto, sitúe el cursor sobre el botón + en la esquina inferior derecha de la pantalla API Catalog (accesible desde el menú API Design) y haga clic en la opción Import an API. Se abrirá la siguiente ventana modal:

import openapi

Introduzca un nombre y una versión para la API que se creará y haga clic en Select file para elegir un archivo de su máquina para importar. Los formatos aceptados son JSON y YAML.

La versión original de la especificación de la documentación importada se mantendrá internamente en el sistema.

Orientaciones para el uso de la especificación OpenAPI 3.0

Campo servers

La especificación OpenAPI 3.0 incluye el campo servers, que define las URLs base de la API e indica a dónde deben enviarse las solicitudes. Especifica los entornos (producción, homologación, desarrollo, etc.) en los que la API está disponible y contiene dos subcampos:

Nombre del campo Tipo Descripción

url (obligatorio)

string

Define la URL completa de la API.

description (opcional)

string

Describe el nombre del entorno especificado por la URL. El campo description será utilizado por Developer Portal para indicar en qué entornos está desplegada la API.

Ejemplo:

servers:
  - url: https://api.ejemplo.com/v1
    description: Entorno de producción
  - url: https://sandbox.ejemplo.com/v1
    description: Entorno de prueba

  • Reglas para el campo url

    1. Obligatoriedad del basePath en la creación de la API

      • Incluso si no desea proporcionar la URL completa, es necesario proporcionar al menos el basePath (ej.: /v1, /api). En ese caso, la API se creará, pero no se desplegará.

    2. URL completa para despliegue automático

      • Si proporciona la URL completa (ej.: ejemplo.com), la API se creará y desplegará automáticamente en el entorno correspondiente.

    3. Restricción al uso mixto de URLs relativas y completas

      • No está permitido combinar URLs relativas (basePath) y URLs completas en el mismo bloque de servers. Si esto ocurre, se mostrará el siguiente mensaje de error:

        Error: Mixing relative and absolute URLs in the servers field is not allowed.

  • Reglas para el campo description

El campo description no es obligatorio y no se valida durante la importación. Sin embargo, sigue las siguientes reglas de comportamiento:

  1. Cuando la URL proporcionada sea incompleta (solo con el basePath) y el campo description se complete con el valor XXX o se deje vacío

    • La API se creará sin la validación de este campo, es decir, cualquier valor ingresado en él será ignorado.

    • Cuando la API se despliegue, el valor del campo description se reemplazará por el nombre del entorno del despliegue.

  2. Cuando la URL proporcionada sea completa y el campo description se complete con el valor XXX o se deje vacío

    • La API se desplegará automáticamente en el entorno correspondiente a la URL proporcionada.

    • El campo description se completará con el nombre del entorno de acuerdo con la URL proporcionada.

  • Ejemplos

    1. Sin URL completa (necesario proporcionar el basePath):

      servers:
  - url: /v1
    description: Producción

    2. Con URL completa (despliegue automático):

      servers:
  - url: https://api.ejemplo.com/v1
    description: Producción
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]