Publicar as APIs (versão original)

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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 especificação OpenAPI para que os desenvolvedores de apps possam aprender sobre suas APIs. Para mais informações sobre snapshots, consulte O que é um snapshot de uma especificação OpenAPI?.

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

• Uma página de referência da API é adicionada ao seu portal
  A página de referência da API mostra 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. Ela não aparece na lista de páginas do seu portal.

  

• Um link para a página de referência da API foi adicionado à página de APIs
  A página de APIs (incluída no portal de amostra) 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. 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 a API, você cria 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ê modificar a especificação OpenAPI usando o editor de especificação, poderá tirar outro instantâneo dela para refletir as mudanças mais recentes na documentação de referência da API.

Como adicionar compatibilidade com CORS aos proxies de API

Antes de publicar suas APIs, adicione compatibilidade com CORS aos proxies de API para permitir solicitações de origem cruzada do lado do cliente.

O CORS (compartilhamento de recursos entre origens) é um mecanismo padrão que permite que chamadas JavaScript XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de domínios não originais. 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 de um código JavaScript executado no navegador, a chamada vai falhar. Isso acontece porque o domínio que veicula a página no seu navegador não é o mesmo que veicula a API do Twitter. O CORS oferece uma solução para esse problema, permitindo que os servidores ativem o compartilhamento de recursos entre origens.

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

Observação: a maioria dos navegadores modernos aplica o CORS. Confira a lista completa de navegadores compatíveis. Para uma descrição detalhada do CORS, consulte a Recomendação W3C de compartilhamento de recursos entre origens (em inglês).

Conhecer a página "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, na página de APIs, é possível:

• 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 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" em que o produto de API associado foi removido do Edge. Depois, recrie o produto de API ou exclua a API do seu portal.

Adicionar uma API ao portal

Observação: é possível adicionar no máximo 100 APIs ao seu 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.
   Outra opção é selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Clique em + API.
   A caixa de diálogo "Adicionar produto de API ao portal" é exibida.

4. Na guia "Produto de API" da caixa de diálogo, selecione o produto que você quer 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.
   

   Ou selecione:

   • Nenhuma especificação e adicione uma depois que a API for publicada, conforme descrito em Como fazer um snapshot da especificação.
   • Escolha outra especificação para selecionar ou fazer upload de uma nova.

7. Marque a caixa de seleção Publicado para publicar a API no seu portal. Desmarque Publicado se não tiver tudo pronto para publicar a API.
   É possível mudar a configuração mais tarde, conforme descrito em Publicar ou cancelar a publicação de uma API no portal.

8. Em "Público-alvo", selecione uma das seguintes opções para gerenciar o público-alvo da sua 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.

   É possível mudar a configuração mais tarde, conforme descrito em Gerenciar o público-alvo de uma API no seu portal.

9. Clique em Concluir.

Capturar um resumo da especificação

Depois de publicar sua API, a qualquer momento, é possível capturar um novo snapshot da especificação OpenAPI para atualizar a documentação de referência da API que é publicada no portal.

Para criar um snapshot da especificação OpenAPI:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Outra opção é selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API para a qual você quer capturar um snapshot para exibir 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 no menu suspenso "Origem do snapshot" ou clique em Escolher outra especificação para selecionar ou fazer upload de uma nova especificação a ser usada na geração da documentação da API. Se preferir, selecione Nenhuma especificação para remover a especificação atual.

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

A documentação de referência da API é gerada com base na especificação e adicionada à página de 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.
   Outra opção é selecionar 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-alvo de uma API no portal

Gerencie o público-alvo da API no seu portal permitindo o acesso a:

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

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

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Outra opção é selecionar 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-alvo para mostrar as ações.
4. Clique em .
5. Em "Público-alvo", selecione uma das seguintes opções:
   • Usuários anônimos para permitir que todos os usuários vejam o produto da API.
   • Usuários registrados para permitir que apenas usuários registrados vejam o produto de API.
6. Clique em Salvar.

Remover uma API do seu 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.
   Outra opção é selecionar 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 as seguintes 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
  

• Em erros de restrição do CORS (Compartilhamento de recursos entre origens), verifique se o CORS é compatível com seus proxies de API. O CORS é um mecanismo padrão que permite solicitações entre origens do cliente. Consulte Como adicionar compatibilidade com CORS a um proxy de API. Verifique se o CORS também está ativado no navegador.