Criando, Editando e Excluindo APIs

Criando uma API

Para adicionar uma nova API manualmente, você pode clicar no botão Create API, representado pelo ícone + no canto inferior direito da tela. Se você somente deixar o cursor sobre o botão, outras três opções aparecerão:

api home

Ao todo, portanto, você tem estas quatro formas de criar uma API:

  • CREATE API: permite criar uma API inserindo todos os dados manualmente.

  • IMPORT API DOCUMENT: 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 GRAPHQL: permite criar uma API GraphQL inserindo os dados obrigatórios manualmente. Para ver mais, clique aqui.

  • CREATE API IDENTITY: permite criar uma API Identity inserindo os dados obrigatórios manualmente. Para ver mais, clique aqui.

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). A tela de cadastro manual de API é esta aqui:

create api

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 eles nesta seção).

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 (10 segundos) será válido.

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. Para saber mais sobre a criação de times, veja aqui;

  • 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 papel (role) 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. Para saber mais sobre a criação de usuários, clique aqui; para saber mais sobre os diferentes papéis de acesso, clique aqui.

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 (leia mais sobre os cards aqui).

card api

Editando or 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. Veja mais informações sobre a tela de Overview aqui.

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.0.

Para fazer isso, passe o cursor sobre o botão + no canto inferior direito da tela APIs e clique na opção IMPORT API DOCUMENT. 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.

Se o arquivo seguir a especificação OpenAPI 3.0.0, ele será convertido automaticamente para Swagger 2.0 no processo de importação. É importante ter em mente que o arquivo convertido manterá tudo o que for suportado pela especificação Swagger 2.0. Depois, é possível editar a documentação da API — que seguirá a especificação 2.0 — pelo Swagger Editor. Esta documentação ajuda a entender a estrutura básica de um arquivo Swagger 2.0.

Você também pode analisar em mais detalhes as diferenças entre Swagger 2.0 e OpenAPI 3.0.0 lendo a documentação das especificações. Clique aqui para ver sobre Swagger 2.0 e aqui para OpenAPI 3.0.0.

Thanks for your feedback!
EDIT

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