Como projetar e editar APIs

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Siga as instruções nesta página para usar o Cloud Code ao projetar e editar APIs.

Criar APIs com o Gemini Code Assist

Visualização — Gemini Code Assist

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível usar o Cloud Code para projetar APIs da especificação OpenAPI (OAS, na sigla em inglês), versão 3.0 usando o Gemini Code Assist. O Gemini Code Assist pode incluir contexto corporativo para assistência com IA generativa no processo de desenvolvimento da API. O Enterprise Context usa as APIs do hub da API do projeto para fornecer contexto ao gerar novas APIs e está disponível apenas em projetos que usam o hub de APIs.

Consulte Usar o Gemini Code Assist para ver informações sobre as etapas de configuração para usar a funcionalidade nesta seção.

Observação: no momento, o Gemini Code Assist é compatível com o design de APIs que combinam novos objetos com objetos já existentes (se o contexto corporativo estiver ativado). Ele não é compatível com cenários que só reutilizem objetos sem criar novos.

Para gerar uma API, siga estas etapas:

1. Clique na varinha mágica na navegação à esquerda para usar o Gemini Code Assist e criar uma nova especificação de API. Use esse método para criar especificações de API em vez do chat do Gemini Code Assist, que não é compatível com todos os recursos e funcionalidades na criação das especificações de API.
   
2. Insira um prompt que descreva a nova API na janela de entrada Criar uma especificação de API.
   1. Se quiser, selecione um modelo de comando entre os ícones mostrados. Um modelo de comando oferece um framework para que ele ajude você a começar.
   2. Insira um comando. Consulte Como escrever prompts de especificação de API eficazes.
      
      
3. O Gemini Code Assist gera um OAS que define a API.
4. Revise a especificação:
   1. Clique em Mostrar código para analisar a especificação no editor de código.
   2. O painel do renderizador de API mostra uma prévia da API que pode ser visualizada pelos desenvolvedores, incluindo a descrição dela e outras documentações.
   3. Se você já tiver APIs de produção no hub de API, esse contexto empresarial será usado para reutilizar objetos de outras APIs para esse OAS e será enumerado no painel OUTPUT:
      
   4. Seu feedback é muito importante. Forneça feedback sobre a especificação gerada clicando no ícone "Gostei" ou "Não gostei" no painel Swagger.
      
   5. Se quiser editar as solicitações de visualização e gerar a especificação novamente, clique nas setas do histórico de solicitações acima das solicitações para alternar entre as solicitações anteriores.
      
5. Teste a especificação. Quando a nova especificação for concluída, você poderá testá-la usando um servidor simulado. Consulte Testar a API usando um servidor simulado.
6. Clique em Salvar para salvar a nova API com um nome que você preferir.
7. Para criar um proxy de API da Apigee com base nessa especificação, clique em Criar proxy de API no menu Mais. O processo de criação cria um pacote de proxy. O novo proxy vai aparecer na lista do menu à esquerda de seus proxies. Consulte o tutorial de criação de proxy de API integrado ao Cloud Code para mais informações sobre como criar proxies no Cloud Code.
   

Como escrever prompts de especificação de API eficazes

A precisão e adequação de uma especificação de API gerada depende muito do comando fornecido ao modelo.

Confira alguns exemplos de comandos bons:

• Crie uma API que permita que os clientes paguem por um pedido usando várias formas de pagamento, como cartões de crédito e débito.
• Aceite ordens de compra para aquisição de grãos de café especiais usando uma API.
• Somos uma pizzaria e queremos criar uma solução on-line personalizada de entrega de pizzas. Crie uma API para aceitar os pedidos de pizza.
• API para empresas de entrega de comida. Os clientes podem pedir uma combinação de pizzas, hambúrgueres ou sanduíches em um único pedido. Cada um desses tipos de alimento tem seu próprio esquema. As pizzas têm recheios e tamanho. Os hambúrgueres têm recheios e tipo de empanada. Os sanduíches têm tipo de pão, carne, vegetais, queijo e instruções personalizadas.

Esses exemplos mostram comandos menos eficazes. Tente evitar solicitações estruturadas como estas:

• Criar uma API para minha loja. O comando contém poucas informações para que o modelo gere uma especificação completa e precisa.
• Criar uma API de reembolso que reutilize o objeto do pedido. Não é necessário especificar quais objetos o Gemini Code Assist precisa reutilizar ao criar novas APIs. O Gemini Code Assist detecta automaticamente os objetos mais adequados para reutilização.

Registrar a API no hub de APIs

Após a revisão e finalização da sua API, registre-a no hub de APIs para disponibilizá-la aos desenvolvedores:

1. Clique em Registrar no hub de APIs.
2. Siga as instruções para registrar a API. Consulte Registrar APIs para informações sobre o registro no hub de APIs e os dados que você precisa fornecer.

Atualizar as APIs do hub de API pelo Cloud Code

É possível salvar uma nova versão das especificações do hub de API ao editá-las no Cloud Code.

Para salvar a especificação como uma nova versão, clique no botão Mais opções... no painel Swagger e clique em Publicar no hub da API. Informe o novo ID da versão da API. A nova versão deve ser exibida na lista de versões da API na lista Hub de API do Cloud Code.

Usar o arquivo de configurações para controlar os comportamentos do Gemini Code Assist

Esta seção explica como usar o arquivo de configurações para gerenciar se o Gemini Code Assist está disponível e como.

Desativar ou ativar o Gemini Code Assist

Depois de configurar a Apigee no Cloud Code (consulte Como configurar a Apigee no Cloud Code), é possível adicionar esta linha ao arquivo de configurações para desativar temporariamente todos os recursos do Gemini Code Assist:

"cloudcode.apigee.gemini.enable": false

Remova a linha ou defina-a como true (o padrão) para reativar o Gemini Code Assist.

Controlar o contexto empresarial na geração de especificações

A geração de OAS pode incluir definições de esquema, metadados e segurança das outras APIs da sua organização. O processo encontra APIs semelhantes usando os nomes e descrições de objetos no catálogo de hub de API que estão no catálogo de hub de API que você tem autorização para acessar. O status da implantação das APIs do hub da API não é considerado.

O contexto empresarial é ativado por padrão.

É possível:

• Confira o número de modificações incluídas por meio do contexto empresarial, se houver, no painel Swagger:
• Confira as modificações incluídas no painel Saída:

Para desativar o contexto empresarial para a nova geração de especificações, adicione estas linhas no arquivo settings.json após "cloudcode.apigee.gemini.enable": true:

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

Em que:

• enabled especifica se o contexto empresarial é ativado de modo geral. Defina como false para desativar o contexto empresarial.
• includeMetadata controla se o contexto de metadados é incluído. Esta configuração inclui ou exclui metadados de outras APIs no hub da API. includeMetadata só é aplicável quando enabled está definido como true.
• includeSchema controla se o contexto do esquema está incluído. Esta configuração inclui ou exclui informações de esquema de outras APIs no hub da API. includeSchema só é aplicável quando enabled está definido como true.
• includeSecurity controla se o contexto relacionado à segurança é incluído. Esta configuração inclui ou exclui informações de segurança de outras APIs no Hub de APIs. includeSecurity só é aplicável quando enabled está definido como true.

Editar APIs

Se quiser usar o Cloud Code para editar APIs atuais que fazem parte do seu catálogo do hub de APIs, siga estas instruções. As alterações feitas no Cloud Code podem ser salvas novamente no hub da API.

Estas instruções são destinadas a usuários que não usam o complemento Gemini Code Assist para a Apigee. Para informações sobre outras funcionalidades disponíveis com o Gemini Code Assist ao projetar e editar APIs, consulte Criar uma API com o Gemini Code Assist.

Observação: no momento, todas as mudanças feitas na API salvas no hub da API precisam ser salvas como uma nova versão.

Para editar uma especificação de API:

1. Verifique se o projeto selecionado no Cloud Code é aquele com o catálogo do hub de APIs contendo a API que você quer editar.
2. Na navegação à esquerda, expanda a árvore do Hub da API.
3. Selecione na lista a API e a versão que você quer editar.
4. Edite a especificação no painel de edição. Também é possível visualizar as operações da API no painel Swagger.
5. Se quiser, teste a API usando um servidor simulado.
6. Salve as mudanças como uma nova versão usando o botão Mais no painel Swagger e depois Publicar no hub da API. Confirme ou atualize a versão quando solicitado e salve as alterações no hub de API. A nova versão deve ser exibida na lista de versões da API na lista Hub de API do Cloud Code.

Testar a API usando um servidor simulado

Teste sua API usando um servidor simulado local. O servidor simulado local está instalado e disponível por padrão.

Usar o servidor simulado local

O servidor simulado local aceita solicitações para essa API e emula respostas. Ele só pode ser usado durante a sessão atual pelo usuário atual.

Observação: é possível que o servidor simulado local não funcione corretamente ao usar o VS Code Remote Explorer. Às vezes, o servidor simulado local não pode ser iniciado. Nesse caso, elE não estará disponível na lista suspensa.

Para usar o servidor simulado local:

1. Selecione o servidor simulado local (servidor de desenvolvimento) o menu suspenso Servidores.
   
2. Abra um caminho e clique em Testar.
   
3. Preencha todos os parâmetros da solicitação e clique em Executar.
   
4. Também é possível enviar solicitações usando curl em um comando. Use o endereço e a porta do servidor no menu suspenso Servidores.