Diseñar y editar APIs

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página se explica cómo diseñar y editar APIs en Apigee con Cloud Code, aprovechando Gemini Code Assist para acelerar la creación, la edición y la gestión de especificaciones de APIs.

Antes de empezar

Antes de usar las funciones de esta guía, haz lo siguiente:

• Asegúrate de haber completado los pasos de configuración de Configurar la gestión de APIs de Apigee en Cloud Code para VS Code, incluido Usar Gemini Code Assist con Apigee.
• Asegúrate de que tu cuenta de usuario tenga los roles necesarios que se indican en Roles necesarios para usar Gemini Code Assist en Apigee para cada tarea.

Escribir peticiones eficaces para especificaciones de API

Cuando crees y edites especificaciones de APIs, le darás instrucciones a Gemini Code Assist en Apigee. La precisión y la idoneidad de las especificaciones de API generadas dependen en gran medida de las peticiones que se proporcionen al modelo.

Para escribir peticiones eficaces de creación y edición de especificaciones de API, sigue estos consejos:

• Con Gemini Code Assist Chat, usa siempre el identificador de Apigee (@Apigee) al principio de tus peticiones para crear o editar especificaciones de APIs. El controlador de Apigee te permite acceder a la herramienta de Apigee, que incluye las funciones de desarrollo de especificaciones de API sólidas y completas que se describen en esta guía.
• Usa un lenguaje natural: formula tus peticiones como si te dirigieras a una persona que va a crear las especificaciones.
• Sé específico: proporciona requisitos exactos siempre que sea posible, como que tu API de programación de citas de la clínica dental debe incluir varios tipos de citas y varias ubicaciones de la clínica.
• Aprovecha el contexto empresarial sin especificar nombres de objetos: Gemini Code Assist detecta y reutiliza de forma inteligente los esquemas, los metadatos y las definiciones de seguridad del catálogo de tu centro de APIs. Aunque no es necesario que especifiques los nombres exactos de los objetos, puedes hacer referencia a esta función incluyendo frases como Use API Hub o Leverage Enterprise Context en tu petición.
• Usa peticiones de seguimiento para iterar en tus APIs: puedes usar peticiones como "Elimina la entidad de ubicaciones de esta API" para hacer cambios en una API.

Estos son algunos ejemplos de peticiones menos y más eficaces para crear y editar especificaciones de APIs:

Petición menos eficaz	Explicación de la petición	Mejor(es) petición(es)
"Crea una API para mi tienda".	Esta petición contiene muy poca información para que el modelo genere una especificación completa y precisa.	"Crea una API para mi tienda para que los clientes puedan consultar la disponibilidad de los productos y añadir artículos a su carrito de la compra". "Crea una API que permita a los clientes pagar un pedido con varios métodos de pago, como tarjetas de crédito y débito".
"Crea una nueva API de reembolsos que reutilice el objeto de pedido".	No especifiques qué objetos debe reutilizar Gemini Code Assist al crear APIs, ya que Gemini Code Assist detecta automáticamente los objetos más adecuados para reutilizar.	"Crea una nueva API de reembolsos que permita a los clientes solicitar el reembolso de un pedido anterior".
"Crea una API para un servicio de entrega".	La API generada será demasiado genérica.	"Somos una pizzería y queremos una solución online personalizada para la entrega de pizzas. Crea una API para aceptar los pedidos de pizza con el tamaño y los ingredientes". "API para empresas de comida a domicilio. Los clientes pueden pedir una combinación de pizzas, hamburguesas o sándwiches en un solo pedido. Cada uno de esos tipos de comida tiene su propio esquema. Las pizzas tienen ingredientes y tamaño. Las hamburguesas tienen ingredientes y un tipo de carne. Los bocadillos tienen tipo de pan, tipo de carne, verduras, queso e instrucciones personalizadas".

Diseñar APIs con Gemini Code Assist

Puedes usar Gemini Code Assist en Cloud Code para diseñar APIs con especificaciones de OpenAPI (OAS), versión 3.0. Las APIs diseñadas pueden incluir el contexto de tu empresa al generar nuevas APIs y solo están disponibles en proyectos que usen API Hub.

Consulta la sección Antes de empezar para obtener información sobre los pasos de configuración necesarios para usar las funciones de esta sección.

Para generar una nueva API con Gemini Code Assist, sigue estos pasos:

1. Usa uno de estos métodos para acceder a la petición de creación de especificaciones de API:
   • Desde Gemini Code Assist: Chat: en la ventana de chat, introduce el identificador de Apigee, @Apigee, y selecciona la herramienta de Apigee.
     
   • En Apigee en Cloud Code: haz clic en la varita mágica de la fila de Apigee. Se carga Gemini Code Assist: Chat. Invoca la herramienta de Apigee con @Apigee para empezar a crear la especificación.
     
2. Selecciona Crear especificación de API en las opciones de la herramienta Apigee.
3. Completa la petición con una descripción de tu nueva API. Consulta Escribir peticiones eficaces para especificaciones de APIs. No copies y pegues el identificador @Apigee. En su lugar, completa la petición escribiendo o pegando el texto después del identificador).
4. Envía la petición.
5. Gemini Code Assist genera un OAS que define la API. Este proceso puede tardar hasta un minuto. Si tu centro de APIs incluye otras APIs, la nueva OAS puede incorporar objetos y contexto de tu catálogo. El resumen de la conversación contextual proporciona información sobre la API generada y las fuentes utilizadas.
6. Revisa la especificación generada. Tanto la especificación de código YAML como el panel de Swagger de la nueva API se muestran automáticamente en pestañas.
7. Una vez que hayas completado la nueva especificación, puedes probarla con un servidor simulado. Consulta Probar una API con un servidor simulado.
8. Para guardar la nueva API en tu catálogo de API Hub, consulta el artículo Publicar APIs en API Hub.
9. Para crear un paquete de proxy de API de Apigee a partir de esta especificación, consulta Guardar APIs como paquetes de proxy de API.

Editar APIs

Puedes editar las APIs que hayas guardado de forma local o desde el catálogo de tu centro de APIs. Los cambios que hagas en Cloud Code se pueden guardar en el centro de APIs o guardar como un paquete de proxy de API de Apigee.

Editar una especificación de API desde el centro de APIs

Para editar una especificación de API almacenada en tu catálogo del centro de APIs, sigue estos pasos:

1. Asegúrate de que el proyecto que has seleccionado en Cloud Code es el proyecto con el catálogo del centro de APIs que contiene la API que quieres editar.
2. En el menú de navegación de la izquierda, despliega el árbol API Hub de la sección Apigee.
3. Seleccione la API y la versión que quiera editar de la lista.
4. Consulta las operaciones de la API en el panel de Swagger. En el panel de Swagger, haz clic en Ver código para abrir el archivo YAML en una pestaña de edición.

Editar una especificación de API almacenada localmente

Para editar una especificación de API almacenada localmente, abre el archivo de especificación de API en Cloud Code. Puedes actualizar la especificación manualmente o usar Gemini Code Assist Chat para iterar en ella.

Iterar especificaciones de APIs con Gemini Code Assist Chat

Puedes modificar una especificación de API con Gemini Code Assist Chat:

1. Carga el archivo de especificación en Cloud Code siguiendo las instrucciones para una especificación de API del Centro de APIs o un archivo de especificación de API local.
2. Comprueba que el archivo YAML que contiene la especificación sea la pestaña activa en tu editor.
3. En la ventana de chat de Gemini Code Assist, introduce el identificador de Apigee, @Apigee, y selecciona la herramienta de Apigee.
4. Introduce la petición de actualización de la especificación. Consulta las directrices para escribir peticiones eficaces de especificaciones de API.
5. También puedes probar tu API con un servidor simulado.
6. Para guardar la nueva API en tu catálogo de API Hub, consulta el artículo Publicar APIs en API Hub.
7. Para crear un paquete de proxy de API de Apigee a partir de esta especificación, consulta Guardar APIs como paquetes de proxy de API.

Publicar APIs en el centro de APIs

Si usas API Hub, puedes poner tus APIs a disposición de otros desarrolladores registrándolas en API Hub:

1. En el panel de Swagger de una especificación de API nueva o editada, haz clic en Publicar en el Centro de APIs.
2. En el formulario, proporcione metadatos de la API para mejorar su visibilidad y la organización de las APIs en el catálogo de su centro de APIs. La mayoría de los campos se rellenan automáticamente a partir de la especificación de la API, pero puedes cambiar los valores. Consulta el artículo Registrar una API para obtener información sobre cómo registrarte en el centro de APIs y la información que debes proporcionar.
   • Nombre visible de la API (obligatorio): nombre de la API que verán otros desarrolladores.
   • Descripción de la API (opcional): descripción de la API para referencia interna o de desarrolladores.
   • Nombre del propietario de la API (opcional): nombre del propietario de la API.
   • Correo del propietario de la API (opcional): la dirección de correo del propietario.
   • Versión de la API (obligatorio): la versión de la API.
   • Fase del ciclo de vida (opcional): selecciona una fase de la lista.
3. Haz clic en Publicar para publicar la API en el centro de APIs.
4. Después de un breve retraso, los cambios deberían aparecer en el árbol del API Hub de la sección Apigee de Cloud Code.

Probar APIs con un servidor simulado

Puedes probar tu API con un servidor simulado local o con un servidor simulado remoto basado en Google Cloud. El servidor simulado local se instala y está disponible de forma predeterminada, mientras que los servidores simulados se deben configurar y gestionar. Google Cloud

Usar el servidor simulado local

El servidor simulado local acepta solicitudes a esta API y emula respuestas. Solo puede usarlo el usuario actual durante la sesión actual. Sin embargo, a diferencia del servidor simulado remoto, no requiere configuración ni gestión y no genera costes.

También servidores simulados locales:

• No funciona cuando se usa Editor de Cloud Shell o Cloud Workstations.
• Puede que no funcione correctamente al usar el Explorador remoto de VS Code.

Para usar el servidor simulado local, sigue estos pasos:

1. Selecciona el servidor simulado local en el menú desplegable Servidores (si aún no lo has hecho):
   
2. Abre una ruta en el panel de Swagger y haz clic en Probar.
   
3. Rellene los parámetros de la solicitud y haga clic en Ejecutar.
   

Usar un servidor simulado remoto

Un servidor simulado remoto te permite crear una instancia de servidor simulado persistente que, a diferencia del servidor simulado local, se puede compartir y usar con otros miembros de tu organización para probar la nueva API. Los servidores simulados remotos solo se pueden usar con APIs registradas en el centro de APIs.

Los servidores simulados remotos no se actualizan automáticamente con los cambios que hagas en la API después de implementar el servidor simulado, así que espera a añadir el servidor simulado hasta que hayas creado la API por completo.

Al desplegar un Google Cloud servidor simulado remoto, se crea un servicio de Cloud Run. Compila una imagen de contenedor para el servidor simulado con Cloud Build y sube la imagen de contenedor a Cloud Artifact Registry en tu proyecto de Google. Consulta ¿Qué es Cloud Run? Gestión de servicios y la documentación de Artifact Registry

Puedes usar la cuenta de servicio predeterminada o proporcionar una cuenta de servicio más restringida para desplegar la aplicación de Cloud Run. Consulta Gestionar APIs de Cloud y bibliotecas de cliente de Cloud en Cloud Code para VS Code para obtener más información.

Importante: Eres responsable de los costes y el mantenimiento del servidor simulado remoto después de crearlo. También eres responsable de eliminarla cuando ya no la necesites o no la utilices. Consulta la página Precios de Cloud Run para obtener información sobre los precios, incluidas las opciones de nivel gratuito.

Para implementar un servidor simulado remoto, sigue estos pasos:

1. Selecciona Deploy mock server (Implementar servidor simulado) en el panel de Swagger.
2. Si tu API aún no está registrada en el centro de APIs, regístrala cuando se te pida.
3. Especifica los detalles del servidor simulado remoto: Nombre del servidor, Servidor seguro, Cuenta de servicio (déjalo vacío para usar la cuenta de servicio predeterminada) y si quieres añadir la URL del servidor a la especificación de la API. Haz clic en Crear para crear el servidor simulado remoto.
   Importante: No crees varios servidores simulados remotos con el mismo nombre, aunque la interfaz de usuario no te lo impida en este momento.
4. La generación del servidor simulado remoto requiere varios minutos. Puedes ver el progreso en el panel OUTPUT de Cloud Code y en la ventana emergente de notificación de la esquina inferior derecha de VS Code.
5. Una vez que se haya completado el proceso de creación del servidor simulado remoto, verás la URL del servidor remoto en la lista de servidores del panel de Swagger y en el panel OUTPUT.
6. Para usar el servidor simulado, abre una ruta y haz clic en Probar.
   
   
   Rellene los parámetros de solicitud y haga clic en Ejecutar.
   
   
   También puedes enviar solicitudes usando curl desde una petición. Usa la dirección y el puerto del servidor del menú desplegable Servidores.

Para compartir el acceso al servidor simulado con otros usuarios, sigue estos pasos:

1. Asigna el rol de invocador a otros usuarios para el servicio implementado. Consulta Autenticar desarrolladores.
2. Cuando los usuarios hacen la solicitud al servidor simulado, siguen las instrucciones de Probar tu servicio privado.

Para gestionar los servidores simulados remotos implementados, sigue estos pasos:

1. Ve al hub de APIs de Apigee.
2. Busca la API para ver todas las implementaciones de la API, incluidos los servidores simulados remotos.
3. Usa la URL del recurso para ir a la implementación y gestionarla deteniendo, eliminando y realizando otras acciones en el servidor simulado.

Guardar APIs como paquetes de proxies de APIs

Puedes guardar tu API como un paquete de proxy de API de Apigee para trabajar en ella en tu entorno de desarrollo local de Apigee. Para obtener información sobre cómo trabajar con proxies de API en Cloud Code, consulta el artículo sobre cómo desarrollar proxies de API.

1. En el panel de Swagger, haz clic en Crear paquete de proxy de API.
2. En el campo de petición, ponle un nombre a tu proxy de API y continúa.
3. Tu proxy de API aparecerá en el menú de la izquierda de Apigee, en tu espacio de trabajo local, en apiproxies.

Controlar el contexto empresarial en la generación de especificaciones

La generación de OAS puede incluir definiciones de esquema, metadatos y seguridad de otras APIs de tu organización. El proceso busca APIs similares usando los nombres y las descripciones de los objetos. No se tiene en cuenta el estado de implementación de las APIs del centro de APIs.

El contexto de empresa está habilitado de forma predeterminada.

Para inhabilitar el contexto de empresa en la generación de nuevas especificaciones, añade estas líneas al archivo settings.json después de "cloudcode.apigee.gemini.enable": true:

"cloudcode.apigee.gemini.options": {
         "enterpriseContext": {
           "enabled": false,
           "includeMetadata": false,
           "includeSchema": false,
           "includeSecurity": false
         }
     }

Dónde:

• enabled especifica si el contexto de empresa está habilitado en general. Asígnale el valor false para inhabilitar el contexto de empresa.
• includeMetadata controla si se incluye el contexto de los metadatos. Este ajuste incluye o excluye metadatos de otras APIs en el centro de APIs. includeMetadata solo se aplica cuando enabled se define como true.
• includeSchema controla si se incluye el contexto del esquema. Este ajuste incluye o excluye la información del esquema de otras APIs en el centro de APIs. includeSchema solo se aplica cuando enabled se define como true.
• includeSecurity controla si se incluye el contexto relacionado con la seguridad. Este ajuste incluye o excluye información de seguridad de otras APIs en el centro de APIs. includeSecurity solo se aplica cuando enabled se define como true.