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. No caso da importação de um arquivo Swagger, a API já é criada com a possibilidade de edição dos 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). Além de letras e números, estes são os caracteres aceitos no cadastro do caminho:

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

    • Dentro de chaves (path parameter): - _

Veja também:

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:

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 sã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 mais detalhes, acesse as páginas sobre Resources e 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 permite o uso imediato da sua API.

Depois de cadastradas, as APIs ficam dispostas em cards.

card api

Editando uma API

Para ter acesso à tela de edição da API, clique sobre o card. Você será direcionado para a tela de Overview.

Para editar as informações da API, clique em Edit API, localizado no canto superior direito da tela.

edit api

A tela de Overview é destinada exclusivamente à visualização das informações. Qualquer alteração na API só pode ser realizada na tela de Edit API.

Para mais informações, consulte a documentação da tela de Overview.

Informações gerais

Na área superior da tela de Edit API, são exibidas as informações gerais da API e as principais ações do fluxo de edição.

general information

Nesta área, é possível:

  • visualizar o Name da API, o Type (REST ou GraphQL) e se a API é Identity;

  • consultar a quantidade de Apps associados e a Revision selecionada.

  • habilitar o editor do Swagger.

  • acessar o API Trace.

  • consultar a data de criação da API.

  • visualizar os planos associados à API, quando houver.

Ações de salvamento

Na área de informações gerais, também estão disponíveis as ações:

  • Save: Salva todas as alterações realizadas em todas as abas da API. O salvamento não é limitado à aba ativa; a API é salva como um todo.

  • Save as new revision: Salva as alterações criando uma nova Revision da API.

  • Qualquer alteração realizada só é efetivada após clicar em Save.

  • Exceção: as ações de Deploy e Undeploy são executadas imediatamente, independentemente do botão Save.

Menu de ações

Ao lado do botão Save, está disponível o menu de ações (botão de mais opções ⋮), que reúne operações da API, como criação de nova versão, clonagem, exportação e exclusão.

acoes edit api

Para deletar uma API, é obrigatório digitar delete para confirmar a ação.

Abas de navegação

API Definitions

A aba API Definitions permite configurar as definições básicas da API, como identificação, escopo organizacional (contexto, organização e times) e opções de exposição no Portal.

O campo Description permite ajustar o tamanho da área de edição. Utilize o controle no canto inferior direito do campo para expandir ou reduzir o espaço de digitação.

A funcionalidade API Portal Settings nessa aba permite configurar a visibilidade e a disponibilidade da API no Portal de Desenvolvedores. As opções disponíveis são:

  • Allow Apps link: quando ativada, a API fica disponível na seção Register New App do Portal de Desenvolvedores. Caso contrário, a API não poderá ser consumida por apps.

  • Show iterative documentation (Swagger): quando ativada, a API fica disponível para testes no Portal de Desenvolvedores. Utilize o botão Add try it out environments para selecionar os ambientes de teste e a revisão que será aplicada.

As configurações disponíveis em API Portal Settings aplicam-se apenas a Portais baseados na stack Drupal.

No novo Portal de Desenvolvedores baseado em Strapi, essas configurações aparecem diretamente no Portal Manager.

As alterações realizadas nesta aba só são aplicadas após clicar em Save.

Resources

A aba Resources permite editar os recursos e as operações da API.

Quando há recursos cadastrados, cada item da lista apresenta um menu de ações (botão de mais opções ⋮).

Por meio desse menu, é possível:

  • no nível do Resource:

    • adicionar uma nova operação

    • editar o resource

    • deletar o resource

  • no nível da Operation:

    • editar a operation

    • deletar a operation

As alterações realizadas nesta aba só são aplicadas após clicar em Save.

Flows

A aba Flows permite editar os interceptores aplicados aos recursos e operações da API.

flows edit

O fluxo é aberto diretamente em modo de edição.

Durante a edição, é possível:

  • configurar e ajustar os interceptores do fluxo.

  • utilizar o botão Reset Operation, disponível diretamente no Flow.

  • visualizar um tooltip ao passar o mouse sobre o botão Reset Operation.

  • confirmar a ação de reset por meio de um modal de confirmação.

  • definir o destino da requisição utilizando a opção Set API Destination.

  • O reset da operação só é aplicado após clicar no botão Save.

  • Ao cancelar a edição, nenhuma alteração de reset é aplicada ao Flow.

Environments

A aba Environments permite editar os ambientes nos quais a API está implantada.

environments edit

Nesta aba, é possível:

  • adicionar um novo environment à API por meio da opção Add Environment.

  • realizar ações de Deploy e Undeploy, que são executadas imediatamente após a confirmação, de forma independente do botão Save.

  • confirmar a ação ao alterar o estado do switch de Deploy.

  • copiar a URL do environment utilizando o botão de copy disponível.

  • remover environments diretamente nesta tela, por meio do botão de delete.

  • As ações de Deploy e Undeploy não dependem do botão Save.

  • O modal de Add Environment é o único fluxo em que uma ação executa o salvamento automático da API.

  • A exclusão de environments só pode ser realizada na tela de Edit API.

Timeline

A aba Timeline mostra as mudanças feitas na API, com filtros por período e tipo de mudança.

Excluindo uma API

Para excluir uma API, utilize a opção Delete API, disponível no menu de ações (botão de mais opções ⋮) localizado no canto superior direito da tela.

Para confirmar a exclusão, é obrigatório digitar delete.

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 o 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, segue as seguintes regras:

  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]