Criação de APIs assistida por IA (Beta)

A opção Create API with AI (beta) permite criar APIs REST de forma rápida e fácil com o auxílio de inteligência artificial. É uma funcionalidade ideal para desenvolvedores que desejam economizar tempo e esforço na criação de APIs e otimizar seu fluxo de trabalho.

Nesta página você encontrará tudo sobre o funcionamento dessa opção e como utilizá-la.

Criando uma nova API com o auxílio de IA

Para criar uma nova API com o auxílio de inteligência artificial, clique no botão + Create API, localizado no canto superior direito da tela API Catalog e selecione a opção Create API with AI (beta).

Para que esta funcionalidade seja disponibilizada no seu ambiente, solicite sua liberação ao time de produto por meio do canal de suporte.

A tela seguinte iniciará um processo composto por cinco etapas para a criação da API:

  1. Context

  2. Prompt

  3. Journey

  4. Endpoints

  5. Contract

Você pode avançar pelas etapas por meio do botão Next ou retornar para etapas anteriores clicando no botão Back, ambos localizados no canto inferior direito das telas (quando aplicável). Caso haja algum campo obrigatório não preenchido na tela, o botão Next ficará desabilitado.

Veja a seguir informações sobre cada uma das etapas.

Context

Trata-se de uma etapa opcional, na qual você pode fornecer informações sobre o contexto da API que deseja criar. Isso é feito por meio do envio de links e arquivos que servirão como fontes de conhecimento para o modelo de IA, ajudando-o a entender melhor suas necessidades. Você pode adicionar, por exemplo, documentos e links que contenham definições de processos, nomenclaturas, estruturas de dados e regras de negócio relevantes. É possível adicionar múltiplos links e arquivos.

Os links correspondem a fontes externas de conhecimento (URLs de páginas da web). Para adicionar um novo link, siga estes passos:

  1. Clique no botão Add Link, localizado no canto superior direito da tela.

  2. Na janela modal que se abrir, insira a URL desejada no campo URL.

  3. Clique no botão Save para adicionar o link.

Os links adicionados são exibidos como cartões na seção Links da tela, com cada cartão contendo:

  • parte da URL inserida;

  • data em que o link foi adicionado (Created at);

  • ações disponíveis:

    • ícone de cópia copiar o link;

    • ícone de lápis editá-lo;

    • ícone de lixeira excluí-lo.

Os arquivos correspondem a documentos que você pode enviar para contextualizar o modelo de IA. Os formatos aceitos são PDF, TXT, DOCX e SQL, com tamanho máximo de 5MB cada arquivo. Para adicionar um novo arquivo, siga estes passos:

  1. Clique no botão Add File, localizado no canto superior direito da tela.

  2. Na janela modal que se abrir, dê um nome para esse contexto digitando-o no campo Context Name e clique no botão Select File para selecionar na sua máquina o arquivo desejado.

  3. Clique no botão Save para enviar o arquivo.

Os arquivos adicionados são exibidos como cartões na seção Files da tela, com cada cartão contendo:

  • nome dado ao contexto;

  • data na qual o arquivo foi adicionado (Created at);

  • tipo de arquivo (File type);

  • ações disponíveis:

    • ícone de lápis editá-lo;

    • ícone de lixeira excluí-lo.

Prompt

A segunda etapa do fluxo de criação da API, Prompt, é obrigatória e lhe permite fornecer uma descrição detalhada dos requisitos de negócio da API a ser gerada. O conteúdo inserido será interpretado pela IA para gerar a estrutura da API, incluindo os endpoints, as jornadas e o contrato.

Insira o texto correspondente à descrição no campo presente na tela. O texto inserido deve conter entre 40 e 2000 caracteres. É importante ser o mais claro e específico possível na descrição, para que a IA possa entender suas necessidades e gerar uma API adequada a elas. Você pode incluir detalhes como:

  • funcionalidades desejadas;

  • cenários de uso;

  • tipos de dados que a API deve manipular;

  • regras de negócio específicas;

  • integrações com outros sistemas;

  • requisitos de segurança;

  • qualquer outra informação relevante que ajude o modelo de IA a entender suas necessidades.

Journey

Na etapa Journey, você pode visualizar as jornadas de negócio da API geradas pela IA com base nas informações fornecidas nas duas etapas anteriores. Cada jornada representa um fluxo funcional da API (um recurso) e seu nome e sua descrição serão utilizados como base para a definição dos endpoints na próxima etapa.

Nesta etapa, você pode:

  • visualizar o nome da API (campo API Name:);

  • editar, excluir ou adicionar jornadas conforme necessário;

  • verificar a relevância dos arquivos e links fornecidos na etapa Context em relação ao prompt inserido.

Jornadas

As jornadas identificadas pela IA são exibidas em uma lista na seção Journeys da tela. Cada item representa uma jornada e contém:

  • nome da jornada;

  • descrição da jornada;

  • ações disponíveis:

    • ícone de lápis permite alterar o nome ou a descrição da jornada;

    • ícone de lixeira exclui a jornada.

Além desses, há o botão Add Journey, localizado acima da lista de jornadas à direita, que permite adicionar manualmente uma nova jornada à lista, a fim de contemplar fluxos não detectados automaticamente pela IA.

Relevance Score

Abaixo da seção Journeys, há a seção Relevance Score, que exibe o nível de relevância dos arquivos e links fornecidos como contexto na etapa Context em relação ao prompt inserido.

Cada contexto é representado por um cartão contendo:

  • nome do contexto;

  • pontuação de relevância (Score).

Essas informações são úteis para avaliar quais contextos estão sendo mais influentes na geração das jornadas. Pontuações mais altas indicam que o conteúdo do contexto está mais alinhado à descrição do prompt, o que pode afetar diretamente a qualidade das jornadas e dos endpoints gerados.

Contextos irrelevantes ou genéricos podem ser descartados para evitar ruído na geração das jornadas e dos endpoints.

Endpoints

Na etapa Endpoints, você pode visualizar os endpoints gerados pela IA com base nas jornadas criadas na etapa anterior. Para cada jornada, um ou mais endpoints são gerados. Cada endpoint representa uma operação específica que a API pode realizar e é composto por um método HTTP, um caminho (path) e a descrição correspondente.

Cada jornada é exibida na tela em um cartão contendo:

  • Nome da jornada: identifica a jornada;

  • Descrição: breve explicação sobre o objetivo da jornada e suas funcionalidades;

  • Tabela de endpoints, com as seguintes colunas:

    • METHOD: método HTTP usado (GET, POST, PATCH, etc.).

    • PATH: caminho da rota da API que representa a ação.

    • SUMMARY: descrição da finalidade do endpoint.

Abaixo da tabela de endpoints, há ainda botões de ação, que permitem:

  • ícone de lápis modificar ou remover endpoints específicos da jornada, bem como adicionar novos endpoints a ela.

  • ícone de lixeira excluir a jornada e todos seus endpoints.

Contract

Na etapa Contract, você pode visualizar e baixar o contrato da API gerado pela IA com base nas informações fornecidas nas etapas anteriores, bem como criar a API diretamente no API Management.

Na tela, são exibidos os seguintes metadados do contrato:

  • Contract: Nome da API.

  • Version: Versão do contrato gerado.

  • OpenAPI: Versão do padrão OpenAPI utilizada na geração do contrato.

  • Contract Description: Descrição do contrato.

Por meio dos botões localizados no canto inferior direito, você pode realizar as seguintes ações:

  • ícone de lixeira excluir o contrato.

  • ícone de código visualizar o contrato em formato bruto (YAML).

  • ícone do swagger visualizar o contrato como uma documentação interativa.

  • ícone de seta para baixo baixar o arquivo do contrato.

  • Generate API: cria a API no API Management com base no contrato gerado.

Thanks for your feedback!
EDIT

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