Criando, Editando e Excluindo APIs

Criando uma API

Para adicionar uma nova API manualmente, clique no botão + Create API, localizado no canto superior direito da tela API Catalog. Um menu será aberto com as seguintes opções para a criação de APIs:

api home

  • Create API: permite criar uma API REST pela interface do API Management inserindo todos os dados manualmente.

  • Create Identity: permite criar uma API Identity inserindo os dados obrigatórios manualmente.

  • Create GraphQL: permite criar uma API GraphQL inserindo os dados obrigatórios manualmente.

  • Import an API: permite criar uma API importando um arquivo de documentação em formato JSON ou YAML. Veja mais sobre a importação e as versões de especificação aceitas abaixo.

  • Create API with AI (beta): crie uma nova API REST com o auxílio de inteligência artificial. Consulte o guia completo dessa opção.

Para que a opção Create API with AI (beta) seja disponibilizada no seu ambiente, solicite sua liberação ao time de produto por meio do canal de suporte.

Ao clicar em Create API, você deverá selecionar, na janela modal que se abrirá, qual especificação a API deverá seguir: Swagger 2.0 ou OpenAPI 3.0. A versão da especificação selecionada será mantida internamente pelo sistema.

Após a escolha de uma das opções citadas acima, a tela de cadastro será exibida e os campos obrigatórios devem ser preenchidos (com exceção da opção de importar um arquivo Swagger, que já cria a API, com a possibilidade de editar os campos).

  • Nos campos API Name e Description não são aceitos os caracteres '<' e/ou '>'.

  • No campo Base path, você deve incluir o caminho base da API. Ele formará parte da URL de acesso à API (que será complementada pelo inbound address e environment de implantação). Fora letras e números, estes são os caracteres aceitos no cadastro do caminho:

    • Fora de chaves: ! @ $ & ( ) - _ = ' ; : ~ +

    • Dentro de chaves (path parameter): - _

Se já houver algum ambiente cadastrado em Environments, a opção Deployable Environments será exibida. Caso contrário, o ambiente pode ser adicionado posteriormente.

Leia mais sobre Environments.

A opção Access token expires in determina o período de tempo de expiração do token para uma determinada API. Caso você não estabeleça um valor, o tempo padrão de 3600 segundos será considerado.

A opção Context está relacionada à visibilidade da sua API, que será exibida apenas para os usuários autorizados. As opções são:

  • Organization: a API estará visível para todos os usuários logados no sistema;

  • Teams: a API será visível para os usuários membros do time selecionado.

    Saiba mais sobre a criação de times.

  • Only me: a API será visível apenas para o usuário que a criou;

  • Add users: a API será visível também para os usuários adicionados, conforme mostra a imagem abaixo:

api add user

Todos os usuários existentes no API Manager serão exibidos. Para alterar a permissão de um usuário específico, basta escolher entre as opções Can view (pode visualizar) ou Can edit (pode editar).

Embora a opção Can edit conceda ao usuário selecionado a permissão para editar as informações da API, essa permissão não ultrapassará as regras de acesso que foram definidas nas configurações de papéis (roles) desse usuário.

Para configurar corretamente as opções de visibilidade de sua API, é necessário que os usuários e times já estejam cadastrados. Consulte a documentação do Access Control para saber mais sobre a criação de usuários e papéis.

A opção Private API,quando marcada, não permite que a API esteja disponível para consumo no Portal de Desenvolvedores.

Ao clicar em Save and next, os dados básicos da API serão salvos. Os dois próximos passos (Resources e Flows) não são obrigatórios (porém, se a importação de um Swagger tiver sido efetuada anteriormente, os dados dos recursos já estarão preenchidos). Para maiores detalhes, acesse as páginas sobre Resources and Flows.

A última etapa na criação da API é a tela Publish:

create api publish

Nela é possível realizar o deploy da API, caso a opção Environments tenha sido selecionada no início do cadastro. É possível também criar templates de teste, que gerarão um plano e uma app para serem vinculados à API cadastrada. Essa opção possibilitará o uso imediato da sua API.

Depois de cadastradas, as APIs ficam dispostas em cards.

card api

Editando ou excluindo uma API

Para ter acesso à tela de edição e exclusão da API, clique sobre o card. Você será direcionado para a tela de Overview. As informações podem ser editadas clicando-se no botão Edit. No canto inferior direito, há o botão Delete, para excluir a API.

Leia mais informações sobre a tela de Overview.
editing
api action overview

Importação de APIs

É possível criar APIs a partir da importação de arquivos de documentação que sigam a especificação OpenAPI. As versões da especificação aceitas são: Swagger 2.0 ou OpenAPI 3.0.

Para fazer isso, passe o cursor sobre o botão + no canto inferior direito da tela API Catalog (acessível pelo menu API Design) e clique na opção Import an API. A seguinte janela modal será aberta:

import openapi

Digite um nome e versão para a API que será criada e clique em Select file para escolher um arquivo de sua máquina para importar. Os formatos aceitos são JSON e YAML.

A versão original da especificação da documentação importada será mantida internamente pelo sistema.

Orientações para uso da especificação OpenAPI 3.0

Campo servers

A especificação OpenAPI 3.0 inclui o campo servers, que define as URLs base da API e indica para onde as requisições devem ser enviadas. Ele especifica os ambientes (produção, homologação, desenvolvimento etc.) em que a API está disponível e contém dois subcampos:

Nome do campo Tipo Descrição

url (obrigatório)

string

Define a URL completa da API.

description (opcional)

string

Descreve o nome do ambiente especificado pela URL. O campo description será utilizado pelo Developer Portal para indicar em quais ambientes a API está implantada.

Exemplo:

servers:
  - url: https://api.exemplo.com/v1
    description: Ambiente de produção
  - url: https://sandbox.exemplo.com/v1
    description: Ambiente de teste

  • Regras para o campo url

    1. Obrigatoriedade do basePath na criação da API

      • Mesmo que não deseje informar a URL completa, é necessário informar ao menos o basePath (ex.: /v1, /api). Nesse caso, a API será criada, mas não será implantada.

    2. URL completa para implantação automática

      • Caso forneça a URL completa (ex.: exemplo.com), a API será automaticamente criada e implantada no ambiente correspondente.

    3. Restrição ao uso misto de URLs relativas e completas

      • Não é permitido combinar URLs relativas (basePath) e URLs completas no mesmo bloco de servers. Se isso ocorrer, a seguinte mensagem de erro será exibida:

        Error: Mixing relative and absolute URLs in the servers field is not allowed.

  • Regras para o campo description

O campo description não é obrigatório e não é validado durante a importação. No entanto, ele segue as seguintes regras de comportamento:

  1. Quando a URL inserida for incompleta (apenas com o basePath) e o campo description for preenchido com o valor XXX ou deixado vazio

    • A API será criada sem a validação desse campo, ou seja, qualquer valor inserido nele será ignorado.

    • Quando a API for implantada, o valor do campo description será substituído pelo nome do ambiente da implantação.

  2. Quando a URL inserida for completa e o campo description for preenchido com o valor XXX ou deixado vazio

    • A API será automaticamente implantada no ambiente correspondente à URL informada.

    • O campo description será preenchido com o nome do ambiente de acordo com a URL fornecida.

  • Exemplos

    1. Sem URL completa (necessário informar o basePath):

      servers:
  - url: /v1
    description: Produção

    2. Com URL completa (implantação automática):

      servers:
  - url: https://api.exemplo.com/v1
    description: Produção
Thanks for your feedback!
EDIT

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