Diseño y edición de APIs

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

Consulta la documentación de Apigee Edge.

Sigue las instrucciones de esta página a fin de usar Cloud Code para diseñar y editar APIs.

Diseña APIs con Gemini Code Assist

Vista previa — Gemini Code Assist

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes usar Cloud Code para diseñar APIs de especificación de OpenAPI (OAS), versión 3.0 con Gemini Code Assist. Gemini Code Assist puede incluir contexto empresarial para la asistencia de IA generativa en el proceso de desarrollo de APIs. El contexto empresarial usa las APIs del concentrador de APIs del proyecto para el contexto cuando se generan APIs nuevas y solo está disponible con proyectos que usan el concentrador de APIs.

Consulta Cómo usar Gemini Code Assist si deseas obtener información sobre los pasos de configuración para usar la funcionalidad en esta sección.

Nota: En este momento, Gemini Code Assist admite el diseño de APIs que combinan objetos nuevos con objetos existentes (si el contexto empresarial está habilitado). No admite situaciones para la reutilización de objetos sin la creación de objetos nuevos.

Para generar una API, sigue estos pasos:

1. Haz clic en la varita mágica en el panel de navegación izquierdo para usar Gemini Code Assist y crear una nueva especificación de API. Asegúrate de usar este método para crear especificaciones de API en lugar del chat de Gemini Code Assist, que no admite todas las funciones y funcionalidades cuando se crean especificaciones de API.
   
2. Ingresa una instrucción que describa la API nueva en la ventana de entrada Crear una especificación de la API.
   1. Si lo deseas, selecciona una plantilla de instrucción de los chips de plantillas que se muestran. Una plantilla de instrucción proporciona un marco de trabajo para tu instrucción que te ayuda a comenzar.
   2. Ingresa una instrucción. Consulta Cómo escribir mensajes de especificaciones de API eficaces.
      
      
3. Gemini Code Assist genera un OAS que define la API.
4. Revisa la especificación:
   1. Haz clic en Ver código para revisar las especificaciones en el editor de código.
   2. En el panel del procesador de API, se muestra una vista previa de la API, ya que los desarrolladores pueden verla, incluida la descripción y otra documentación de la API.
   3. Si ya tienes APIs en el concentrador de APIs, ese contexto empresarial se usa para prepropagar objetos de otras APIs a este OAS y se enumeran en el panel OUTPUT:
      
   4. Agradecemos tus comentarios. Para enviar comentarios sobre las especificaciones generadas, haz clic en el ícono de pulgar hacia arriba o de pulgar hacia abajo en el panel de Swagger.
      
   5. Si deseas editar las instrucciones de vista previa y volver a generar la especificación, haz clic en las flechas del historial de instrucciones sobre las instrucciones para moverte entre las instrucciones anteriores.
      
5. Prueba la especificación: Una vez que se complete la nueva especificación, puedes probarla con un servidor de simulación. Consulta Prueba tu API con un servidor de simulación.
6. Haz clic en Guardar para guardar la API nueva con el nombre que elijas.
7. Para crear un proxy de API de Apigee a partir de esta especificación, haz clic en Crear proxy de API en el menú Más. El proceso de creación crea un paquete de proxy. Debería ver el nuevo proxy en la lista del menú de la izquierda de sus proxies. Consulta la explicación sobre la creación del proxy de API que está integrada en Cloud Code para obtener información adicional sobre la creación de proxies desde Cloud Code.
   

Cómo escribir mensajes de especificaciones de API eficaces

La exactitud y la idoneidad de una especificación de API generada dependen en gran medida de la instrucción que se proporcionó al modelo.

Estos son ejemplos de instrucciones buenas:

• Crea una API que permita a los clientes pagar un pedido mediante varias formas de pago, como tarjetas de crédito y débito.
• Acepta pedidos de compra para compras especializadas de granos de café a través de una API.
• Somos una empresa de pizzas y queremos crear una solución de entrega de pizza personalizada en línea. Crea una API para aceptar los pedidos de pizza.
• API para negocio de entrega de alimentos. Los clientes pueden pedir una combinación de pizza, hamburguesas o emparedados en un solo pedido. Cada uno de ellos tiene su propio esquema. Las pizzas tienen ingredientes y tamaño. Las hamburguesas tienen distintas variedades e ingredientes. Los emparedados tienen tipo de pan, tipo de carne, vegetales, queso y también instrucciones personalizadas.

En estos ejemplos, se muestran instrucciones menos eficaces. Evita los mensajes estructurados como los siguientes:

• Crea una API para mi tienda. Este mensaje contiene muy poca información para que el modelo genere una especificación completa y precisa.
• Crea una nueva API de reembolso que reutilice el objeto de pedido. No es necesario especificar qué objetos debe reutilizar Gemini Code Assist cuando creas APIs nuevas. Gemini Code Assist detecta automáticamente los objetos más adecuados para reutilizar.

Registra la API con el concentrador de API

Una vez que tu API se haya revisado y finalizado, puedes hacer que esté disponible para los desarrolladores mediante el registro en el concentrador de APIs:

1. Haz clic en Register to API Hub.
2. Sigue las indicaciones para registrar la API. Consulta Registra API para obtener información sobre cómo registrarte con el concentrador de API y la información que debes proporcionar.

Actualiza las APIs del concentrador de APIs desde Cloud Code

Puedes guardar una versión nueva de las especificaciones del concentrador de APIs cuando las edites desde Cloud Code.

Para guardar la especificación como una versión nueva, haz clic en el botón Más opciones... en el panel de Swagger y Publicar en el concentrador de APIs. Proporciona el ID de la versión de la API nueva. Deberías ver la versión nueva en la lista de versiones de esa API en la lista concentrador de APIs de Cloud Code.

Usa el archivo de configuración para controlar los comportamientos de Gemini Code Assist

En esta sección, se explica cómo administrar si Gemini Code Assist está disponible y de qué manera, desde el archivo de configuración.

Inhabilita o habilita Gemini Code Assist

Una vez que hayas configurado Apigee en Cloud Code (consulta Configura Apigee en Cloud Code), puedes agregar esta línea a tu archivo de configuración para inhabilitar de forma temporal todas las funciones de Gemini Code Assist:

"cloudcode.apigee.gemini.enable": false

Quita la línea o configúrala como true (el valor predeterminado) para volver a habilitar Gemini Code Assist.

Controla el contexto empresarial en la generación de especificaciones

La generación de OAS puede incluir esquemas, metadatos y definiciones de seguridad de las otras APIs de tu organización. El proceso encuentra APIs similares mediante los nombres y las descripciones de objetos en tu catálogo del concentrador de APIs que se encuentran en tu catálogo del concentrador de APIs al que tienes acceso. No se tiene en cuenta el estado de implementación de las APIs del concentrador de APIs.

El contexto empresarial está habilitado de forma predeterminada.

Puedes hacer lo siguiente:

• Consulta la cantidad de modificaciones incluidas en el contexto empresarial, si las hay, en el panel de Swagger:
• Consulta las modificaciones incluidas en el panel Resultado:

Si deseas inhabilitar el contexto empresarial para la generación de especificaciones nuevas, agrega estas líneas en el archivo settings.json después de "cloudcode.apigee.gemini.enable": true:

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

Donde:

• enabled especifica si el contexto empresarial está habilitado en general. Configúralo como false para inhabilitar el contexto empresarial.
• includeMetadata controla si se incluye el contexto de metadatos. Este parámetro de configuración incluye o excluye los metadatos de otras APIs en el concentrador de APIs. includeMetadata solo es aplicable cuando enabled se configura como true.
• includeSchema controla si se incluye el contexto del esquema. Este parámetro de configuración incluye o excluye la información del esquema de otras APIs en el concentrador de APIs. includeSchema solo es aplicable cuando enabled se configura como true.
• includeSecurity controla si se incluye el contexto relacionado con la seguridad. Este parámetro de configuración incluye o excluye la información de seguridad de otras APIs en el concentrador de APIs. includeSecurity solo es aplicable cuando enabled se configura como true.

Edita APIs

Para usar Cloud Code a fin de editar las APIs existentes que forman parte de tu catálogo del concentrador de APIs, sigue estas instrucciones. Los cambios que realices en Cloud Code se pueden volver a guardar en el concentrador de APIs.

Estas instrucciones son para usuarios que no usan el complemento de Gemini Code Assist para Apigee. Para obtener información sobre la funcionalidad adicional que está disponible con Gemini Code Assist cuando diseñas y editas APIs, consulta Diseña una API con Gemini Code Assist.

Nota: En este momento, cualquier cambio en la API que se haya guardado de nuevo en el concentrador de APIs debe guardarse como una versión nueva.

Para editar una especificación de API, sigue estos pasos:

1. Asegúrate de que el proyecto que seleccionaste en Cloud Code sea el proyecto con el catálogo del concentrador de APIs que contiene la API que deseas editar.
2. En el panel de navegación izquierdo, expande el árbol Concentrador de APIs.
3. En la lista, selecciona la API y la versión que deseas editar.
4. Edita la especificación en el panel de edición. También puedes ver las operaciones de la API en el panel de Swagger.
5. De manera opcional, prueba tu API con un servidor de simulación.
6. Guarda los cambios como una versión nueva con el botón Más en el panel de Swagger y, luego, Publica en el concentrador de APIs. Confirma o actualiza la versión cuando se te solicite y vuelve a guardar los cambios en el concentrador de APIs. Deberías ver la versión nueva en la lista de versiones de esa API en la lista concentrador de APIs de Cloud Code.

Prueba tu API con un servidor de simulación

Puedes probar tu API con un servidor de simulación local. El servidor de simulación local está instalado y disponible de forma predeterminada.

Usa el servidor de simulación local

El servidor de simulación local acepta solicitudes a esta API y emula las respuestas. Solo el usuario actual puede usarlo durante la sesión actual.

Nota: Es posible que el servidor de simulación local no funcione correctamente cuando se usa el Explorador remoto de VS Code. Además, en ocasiones, el servidor de simulación local no puede iniciarse. En ese caso, no estará disponible en la lista desplegable.

Para usar el servidor de simulación local, haz lo siguiente:

1. Selecciona el servidor de simulación local (servidor de desarrollo) en el menú desplegable Servidores.
   
2. Abre una ruta y haz clic en Probar.
   
3. Completa los parámetros de solicitud y haz clic en Ejecutar.
   
4. También puedes enviar solicitudes mediante curl desde un prompt. Usa la dirección y el puerto del servidor del menú desplegable Servidores.