Publicar as APIs (versão original)

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Publique APIs no seu portal para disponibilizá-las para consumo pelos desenvolvedores de apps, como descrito nas seções a seguir.

Visão geral da publicação da API

O processo de publicação de APIs no portal é um processo de duas etapas:

1. Selecione o produto de API que você quer publicar no portal.
2. Gere automaticamente a documentação de referência da API com base em um snapshot da sua especificação OpenAPI para permitir que os desenvolvedores de apps aprendam sobre as APIs. Para mais informações sobre snapshots, consulte O que é um snapshot de uma especificação OpenAPI?.

Quando você publica uma API no seu portal, as seguintes atualizações são feitas automaticamente:

• Uma página de referência da API é adicionada ao seu portal
  Essa página exibe a documentação de referência da API que você gera automaticamente com base em um snapshot da sua especificação OpenAPI. Os desenvolvedores podem revisar a documentação da API e clicar em Testar para fazer uma solicitação de API e ver a saída.

  Observação: não é possível editar o conteúdo desta página diretamente, porque ela não aparece na lista de páginas do seu portal.

  

• Um link para a página "Referência da API" foi adicionado à página "APIs"
  A página "APIs" (incluída no portal de exemplo) fornece uma lista de todas as APIs publicadas no seu portal com links para a respectiva documentação de referência da API para mais informações.

  Observação: não é possível editar o conteúdo desta página diretamente, porque ela não aparece na lista de páginas do seu portal.

  

O que é um snapshot de uma especificação OpenAPI?

Cada especificação OpenAPI serve como fonte da verdade durante todo o ciclo de vida de uma API. A mesma especificação é usada em cada fase do ciclo de vida da API, desde o desenvolvimento até a publicação e o monitoramento. Ao modificar uma especificação, é preciso compreender o impacto que as alterações têm na API por meio de outras fases do ciclo de vida, conforme descrito em O que acontece se eu modificar uma especificação?

Ao publicar sua API, você faz um snapshot da especificação OpenAPI para gerar a documentação de referência da API. Esse snapshot representa uma versão específica da especificação no armazenamento de especificações. Se você otimizar a especificação OpenAPI usando o editor de especificações, poderá criar outro instantâneo da especificação para refletir as alterações mais recentes na documentação de referência da API.

Como adicionar suporte a CORS nos proxies de API

Antes de publicar suas APIs, adicione suporte ao CORS nos proxies de API para aceitar solicitações de origem cruzada do lado do cliente.

O Compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que chamadas JavaScript XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de domínios que não são de origem. O CORS é uma solução comumente implementada na política de mesma origem que é aplicada por todos os navegadores. Por exemplo, se você fizer uma chamada XHR para a API do Twitter a partir do código JavaScript em execução no seu navegador, a chamada falhará. Isso ocorre porque o domínio que veicula a página no navegador não é o mesmo que veicula a API do Twitter. O CORS oferece uma solução para esse problema ao permitir que os servidores ativem o recurso se quiserem oferecer o compartilhamento de recursos entre origens.

Para informações sobre como adicionar suporte ao CORS nos proxies de API antes de publicar as APIs, consulte Como adicionar suporte ao CORS em um proxy de API.

Observação: a maioria dos navegadores modernos aplica o CORS. Consulte a lista completa de navegadores compatíveis. Para uma descrição detalhada do CORS, consulte a recomendação do W3C de compartilhamento de recursos entre origens.

Confira a página de APIs

Para acessar a página de APIs:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.

Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.

A lista de APIs é exibida.

Como destacado na figura anterior, a página de APIs permite:

• Ver os detalhes das APIs disponíveis no seu portal
• Adicionar uma API ao portal
• Crie um snapshot da especificação OpenAPI associada a um produto de API para atualizar a documentação de referência da API
• Publicar ou cancelar a publicação de uma API no seu portal
• Gerenciar o público de uma API no seu portal
• Edite a especificação associada (consulte Criar especificações usando o editor de especificações)
• Remover uma API do seu portal
• Identifique rapidamente APIs "órfãs" com produto de API associado que foi removido do Edge e recrie o produto de API ou exclua a API do portal

Adicionar uma API ao seu portal

Observação: é possível adicionar até 100 APIs ao portal.

Para adicionar uma API ao portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Como alternativa, selecione APIs no menu suspenso do portal, na barra de navegação superior.
3. Clique em + API.
   A caixa de diálogo "Add API Product to Portal" é exibida.

4. Na guia Produto da API da caixa de diálogo, selecione o produto de API que deseja adicionar ao portal.
   

5. Clique em Próxima.

6. Selecione a origem a ser usada no snapshot.
   Se você criou o proxy de API incluído no produto de API usando uma especificação OpenAPI, selecione a especificação na lista suspensa.
   

   Também é possível selecionar:

   • Sem especificação e adicione uma mais tarde após a publicação da API, conforme descrito em Como criar um snapshot da especificação.
   • Escolha uma especificação diferente para selecionar ou fazer upload de uma nova especificação.

7. Marque a caixa de seleção Publicado para publicar a API no seu portal. Desmarque Publicado se a API não estiver pronta para ser publicada.
   Você pode mudar a configuração depois, conforme descrito em Como publicar ou cancelar a publicação de uma API no seu portal.

8. Em "Público", selecione uma das seguintes opções para gerenciar o público da API permitindo o acesso a:

   • Usuários anônimos para permitir que todos os usuários visualizem a página.
   • Usuários registrados para permitir que apenas usuários registrados vejam a página.

   Você pode mudar a configuração depois, conforme descrito em Como gerenciar o público-alvo de uma API no seu portal.

9. Clique em Finish.

Capturar um snapshot da especificação

Após a publicação da API, é possível fazer um novo instantâneo da especificação OpenAPI para atualizar a documentação de referência da API publicada no seu portal a qualquer momento.

Para capturar um snapshot da especificação OpenAPI:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Como alternativa, selecione APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API que terá um snapshot para mostrar as ações.

4. Clique em .

   Observação: uma mensagem será exibida se o snapshot estiver com a especificação de origem selecionada.

5. Selecione uma especificação existente no menu suspenso "Origem do snapshot" ou escolha Escolher uma especificação diferente para selecionar ou fazer upload de uma nova especificação que será usada para gerar a documentação da API. Como alternativa, selecione Sem especificação para remover a especificação atual.

6. Clique em Atualizar snapshot (ou Remover snapshot, se você tiver selecionado "Sem especificação").

A documentação de referência da API é gerada a partir da especificação e adicionada à página "Referência da API".

Publicar ou cancelar a publicação de uma API no portal

Para publicar ou cancelar publicação de uma API no portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Como alternativa, selecione APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API que você quer publicar ou cancelar a publicação.
4. Clique em .
5. Marque a caixa de seleção Ativar para publicar a API no portal. Desmarque Ativar para cancelar a publicação da API.
6. Clique em Salvar.

Gerenciar o público de uma API no seu portal

Gerencie o público da sua API no portal permitindo o acesso a:

• Todos os usuários
• Somente usuários registrados

Para gerenciar o público de uma API no seu portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Como alternativa, selecione APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API em que você quer gerenciar o público para mostrar as ações.
4. Clique em .
5. Em "Público", selecione uma das seguintes opções:
   • Usuários anônimos para permitir que todos os usuários vejam o produto de API.
   • Usuários registrados para permitir que apenas usuários registrados vejam o produto de API.
6. Clique em Salvar.

Remover uma API do portal

Para remover uma API do seu portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Como alternativa, selecione APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API na lista para exibir o menu de ações.
4. Clique em .

Resolver problemas com as APIs publicadas

Ao usar o recurso "Testar", se o erro TypeError: Failed to fetch for retornado, considere estas possíveis causas e resoluções:

• Para erros de conteúdo misto, o erro pode ser causado por um problema known swagger-ui. Uma alternativa possível é especificar o HTTPS antes do HTTP na definição de schemes na especificação OpenAPI. Exemplo:

   schemes:
     - https
     - http
  

• Para erros de restrição do Compartilhamento de recursos entre origens (CORS), verifique se o CORS é compatível com os proxies de API. O CORS é um mecanismo padrão que permite solicitações entre origens do cliente. Consulte Como adicionar suporte ao CORS para um proxy de API. Ative o CORS também no navegador.