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): - _

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:

api add user

Se mostrarán todos los usuarios existentes en el API Manager. Para cambiar el permiso de un usuario específico, simplemente elija entre las opciones Can view (puede ver) o Can edit (puede editar).

Aunque la opción Can edit concede al usuario seleccionado permiso para editar la información de la API, este permiso no superará las reglas de acceso definidas en la configuración de rol de ese usuario.

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, acceder 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

Editar o eliminar una API

Para acceder a la pantalla de edición y eliminación de API, hacer clic en la tarjeta de una API. Se le dirigirá a la pantalla Overview. La información puede editarse haciendo clic en el botón Edit. En la esquina inferior derecha, hay el botón Delete para eliminar la API.

Consulte más información sobre la pantalla Overview.
editing
api action overview

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]