Publique suas APIs

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. Renderize a documentação de referência da API de renderização com base em um snapshot do documento da OpenAPI ou do esquema GraphQL. Assim, os desenvolvedores de apps podem aprender sobre suas APIs. Para mais informações sobre snapshots, consulte O que é um snapshot?

O que é publicado no portal?

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

Documentos de referência de API. A interface fornecida depende da publicação da API usando um documento da OpenAPI ou um esquema GraphQL. Consulte:

• SmartDocs (OpenAPI)
• Explorador do GraphQL

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, listadas em ordem alfabética, com links para a respectiva documentação de referência da API para mais informações. Como opção, você pode personalizar o seguinte:

• Imagem exibida para cada card de API
• Categorias usadas para incluir tags em APIs e permitir que os desenvolvedores descubram APIs relacionadas na página de APIs

SmartDocs (OpenAPI)

Quando você publica uma API usando um documento da OpenAPI, a documentação de referência da API SmartDocs é adicionada ao portal.

Os desenvolvedores podem ler a documentação de referência da API SmartDocs e usar o painel Testar esta API para fazer uma solicitação de API e ver a saída. Use esta API para trabalhar com endpoints não seguros ou endpoints protegidos usando a autenticação básica, a chave de API ou a OAuth, com base no método de segurança definido no documento OpenAPI. Para OAuth, os seguintes fluxos são compatíveis: código de autorização, senha e credenciais do cliente.

Clique em para expandir o painel "Teste esta API". O painel expandido permite visualizar a chamada de curl e os exemplos de código em vários formatos, como HTTP, Python, Node.js e muito mais, conforme mostrado abaixo.

Explorador do GraphQL

Quando você publica uma API usando um esquema do GraphQL, ele é adicionado ao seu portal. O Explorador do GraphQL é um playground interativo para executar consultas na API. O explorador é baseado no GraphiQL, uma implementação de referência do ambiente de desenvolvimento integrado GraphQL, desenvolvida pela GraphQL Foundation.

Os desenvolvedores podem usar o Explorador do GraphQL para explorar a documentação interativa baseada em esquema, criar e executar consultas, visualizar resultados de consulta e fazer o download do esquema. Para proteger o acesso à sua API, os desenvolvedores podem transmitir cabeçalhos de autorização no painel Cabeçalhos da solicitação.

Para mais informações sobre o GraphQL, consulte graphql.org.

O que é um snapshot?

Cada documento da OpenAPI ou do GraphQL serve como a fonte da verdade ao longo do ciclo de vida de uma API. O mesmo documento é usado em cada fase do ciclo de vida da API, desde o desenvolvimento até a publicação e o monitoramento. Ao modificar um documento, é 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 um documento?

Quando você publica sua API, cria um snapshot do documento da OpenAPI ou do GraphQL para renderizar a documentação de referência da API. Esse snapshot representa uma determinada versão do documento. Se você modificar o documento, poderá ter outro instantâneo dele para refletir as alterações mais recentes na documentação de referência da API.

Sobre URLs de callback

Se seus aplicativos exigem um URL de callback, como ao usar o tipo de concessão de código de autorização OAuth 2.0 (geralmente chamado de "OAuth de três etapas"), você pode exigir que os desenvolvedores especifiquem um URL de callback ao registrarem seus aplicativos. O URL de callback normalmente especifica o URL de um app designado para receber um código de autorização em nome do app cliente. Para mais informações, consulte Implementar o tipo de concessão do código de autorização.

Você pode configurar se é necessário ou não exigir um URL de callback durante o registro do app ao adicionar uma API ao seu portal. Você pode modificar essa configuração a qualquer momento, conforme descrito em Gerenciar o URL de callback de uma API.

Ao registrar um app, os desenvolvedores precisam inserir um URL de callback para todas as APIs que precisam dele, conforme descrito em Registrar apps.

Configurar o proxy de API para oferecer suporte ao recurso "Testar esta API"

Antes de publicar suas APIs usando um documento da OpenAPI, é preciso configurar seu proxy de API para fazer solicitações no painel "Testar esta API" da documentação de referência da API SmartDocs, conforme descrito a seguir:

• Adicionar suporte para CORS aos seus proxies de API para aplicar solicitações de origem cruzada do lado do cliente
  

  O CORS é 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 normalmente implementada na "política de mesma origem" que é aplicada por todos os navegadores.

• Atualizar a configuração do proxy da API, se você estiver usando a autenticação básica ou o OAuth2

A tabela a seguir resume os requisitos de configuração do proxy da API para oferecer suporte ao painel "Testar esta API" da documentação de referência da API SmartDocs, com base no acesso de autenticação.

Acesso de autenticação	Requisitos de configuração de política
Nenhuma ou chave de API	Adicione suporte ao CORS ao proxy de API. Para facilitar, use a solução de CORS de amostra fornecida no GitHub ou siga as etapas descritas em Como adicionar suporte ao CORS a um proxy de API.
Autenticação básica	Siga estas etapas: Adicione suporte ao CORS ao proxy de API. Para facilitar, use a solução de CORS de amostra fornecida no GitHub ou siga as etapas descritas em Como adicionar suporte ao CORS a um proxy de API. Na política Add CORS AssignMessage, verifique se o cabeçalho Access-Control-Allow-Headers inclui o atributo authorization. Exemplo: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>
OAuth2	Adicione suporte ao CORS ao proxy de API. Para facilitar, use a solução de CORS de amostra fornecida no GitHub ou siga as etapas descritas em Como adicionar suporte ao CORS a um proxy de API. Na política Add CORS AssignMessage, verifique se o cabeçalho Access-Control-Allow-Headers inclui o atributo authorization. Exemplo: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header> Corrija o comportamento não compatível com RFC na política do OAuth2. Por conveniência, use a solução OAuth2 de amostra fornecida no GitHub ou execute as seguintes etapas: Verifique se o elemento <GrantType> na política OAuth2 está definido como request.formparam.grant_type (parâmetro de formulário). Para mais informações, consulte <GrantType>. Verifique se a token_type na política OAuth2 está definida como Bearer, e não como BearerToken padrão.

Conheça o catálogo de APIs

Para ver o catálogo de APIs, siga estas etapas:
1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em Catálogo de APIs na página inicial do portal.
Como alternativa, selecione Catálogo de APIs no menu suspenso do portal, na barra de navegação superior.

A guia APIs do catálogo exibe uma lista das APIs que foram adicionadas ao seu portal.

Conforme destacado na figura anterior, a guia APIs permite que você:

• Ver os detalhes das APIs disponíveis no seu portal
• Adicionar uma API ao portal
• Edite uma API no seu portal realizando uma ou mais das seguintes tarefas:
  • Gerencie o snapshot de um documento associado 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 a visibilidade de uma API no portal:
  • Gerenciar o URL de callback para uma API
  • Gerenciar a imagem de um card de API
  • Marcar uma API usando categorias
  • Editar o título e a descrição da API
• Remover uma API do seu portal
• Gerenciar as categorias usadas para descobrir APIs relacionadas
• Identifique rapidamente especificações que estão desatualizadas ou que foram excluídas da loja de especificações
• 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

Para adicionar uma API ao portal:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.

3. Clique em +.

   A caixa de diálogo "Adicionar um produto de API ao catálogo" é exibida.

4. Selecione o produto de API que você quer adicionar ao seu portal.

5. Clique em Próxima.
   A página de detalhes da API é exibida.

6. Configure o conteúdo da documentação de referência da API e a visibilidade dela no portal:

   Campo	Descrição
   Publicado	Selecione Publicado para publicar a API no seu portal. Desmarque a caixa de seleção se você não estiver pronto para publicar a API. Você pode mudar a configuração depois, conforme descrito em Publicar ou cancelar a publicação de uma API no seu portal.
   Título de exibição	Atualize o título da API exibido no catálogo. Por padrão, o nome do produto da API é usado. Você pode alterar o título de exibição mais tarde, conforme descrito em Editar título e descrição.
   Descrição de exibição	Atualize a descrição da API exibida no catálogo. Por padrão, a descrição do produto da API é usada. Você pode alterar a descrição de exibição mais tarde, conforme descrito em Editar título e descrição.
   Exigir que os desenvolvedores especifiquem um URL de callback	Ative essa opção se quiser exigir que os desenvolvedores de apps especifiquem um URL de callback. É possível adicionar ou atualizar o URL de callback posteriormente, conforme descrito em Gerenciar o URL de callback de uma API.
   Documentação da API	Para usar um documento da OpenAPI: Selecione o documento da OpenAPI. Clique em Selecionar documento. Realize uma das seguintes etapas: Clique na guia Minhas especificações e selecione uma especificação no repositório. Clique na guia Fazer upload do arquivo e faça upload de um arquivo. Clique na guia Importar de um URL e importe uma especificação de um URL. Clique em Selecionar. Para usar um esquema do GraphQL: Selecione GraphQL Schema. Clique em Selecionar documento. Navegue até o esquema do GraphQL e selecione-o. Clique em Selecionar. Outra opção é selecionar Sem documentação e adicionar uma mais tarde, depois que a API for adicionada, conforme descrito em Como gerenciar o resumo do documento.
   Visibilidade da API	Se você não tiver inscrito na versão Beta do recurso de gerenciamento de públicos-alvo, selecione uma das seguintes opções: Usuários anônimos para permitir que todos os usuários visualizem a API. Usuários registrados para permitir que apenas usuários registrados vejam a API. Se você tiver inscrito na versão Beta do recurso de gerenciamento de públicos-alvo, selecione uma das seguintes opções: Público (visível para qualquer pessoa) para permitir que todos os usuários visualizem a API. Usuários autenticados para permitir que apenas usuários registrados vejam a API. Públicos-alvo selecionados para selecionar os públicos-alvo específicos que você quer visualizar na API. Você pode gerenciar a visibilidade do público-alvo posteriormente, conforme descrito em Gerenciar a visibilidade de uma API no seu portal.
   Imagem de exibição	Para exibir uma imagem no card da API na página "APIs", clique em Selecionar imagem. Na caixa de diálogo Selecionar imagem, selecione uma imagem existente, faça upload de uma nova imagem ou forneça o URL de uma imagem externa e clique em Selecionar. Visualize a miniatura da API e clique em Selecionar. É possível adicionar uma imagem depois, conforme descrito em Gerenciar a imagem de um card de API.
   Categorias	Adicione as categorias às quais a API será marcada para permitir que os desenvolvedores de aplicativos descubram APIs relacionadas na página de APIs. Para identificar uma categoria: Selecione uma categoria na lista suspensa. Adicione uma nova categoria digitando o nome dela e pressionando Enter. A nova categoria será adicionada à página "Categorias" e disponibilizada ao adicionar ou editar outras APIs.

7. Clique em Salvar.

Gerenciar o resumo do documento

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

Para gerenciar o instantâneo do documento:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Verifique o status do snapshot. Se ela estiver desatualizada, a seguinte mensagem será exibida:
   
5. Clique em .
6. Realize uma das seguintes tarefas:
   • Para atualizar um snapshot de um documento da OpenAPI que está desatualizado, clique em Atualizar snapshot.
   • Para alterar o documento usado para gerar a documentação da API, acesse "Documentação da API", clique em Selecionar documento e escolha o novo documento.
7. Clique em Salvar.

A documentação de referência da API é renderizada a partir do documento e adicionada à página de referência da API. O status do snapshot é atualizado para o atual:

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

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

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Clique em .
5. Em "Detalhes da API", marque ou desmarque Publicado (listado no catálogo) para publicar ou cancelar a publicação da API em seu portal, respectivamente.
6. Clique em Salvar.

Gerenciar a visibilidade de uma API em seu portal

Gerencie a visibilidade de uma API em seu portal permitindo o acesso a:

• Público (visível para qualquer pessoa)
• Usuários autenticados
• Públicos-alvo selecionados (se você tiver inscrito na versão Beta do recurso de gerenciamento de público-alvo)

Para gerenciar a visibilidade de uma API em seu portal:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Clique em .
5. Em "Visibilidade da API", selecione uma das seguintes opções:

6. Selecione a configuração de visibilidade. Se você tiver inscrito na versão Beta do recurso de público-alvo, selecione uma das seguintes opções:

   • Público (visível para todos) para permitir que todos os usuários vejam a página.
   • Usuários registrados para permitir que apenas usuários registrados vejam a página.
   • Públicos-alvo selecionados para selecionar os públicos-alvo que você quer ver na página. Consulte Como gerenciar os públicos-alvo do seu portal.
   Caso contrário, selecione uma das seguintes opções:
   • 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.

7. Clique em Enviar.

Gerenciar o URL de callback para uma API

Gerenciar o URL de callback para uma API. Consulte Sobre URLs de callback.

Para gerenciar o URL de callback de uma API:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Clique em .
5. Em "Detalhes da API", marque ou desmarque Publicado (listado no catálogo) para publicar ou cancelar a publicação da API em seu portal, respectivamente.
6. Clique em Salvar.

Gerenciar a imagem de um card de API

Gerencie a imagem que aparece com um card de API na página de APIs adicionando ou alterando a imagem atual.

Para gerenciar a imagem de um card de API:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Clique em .

5. Em "Detalhes da API":

   • Se nenhuma imagem estiver selecionada, clique em Selecionar imagem para selecionar ou fazer upload de uma imagem.
   • Clique em Alterar imagem para selecionar ou fazer upload de uma imagem diferente.
   • Clique no x na imagem para removê-la.

6. Clique em Salvar.

Marcar uma API usando categorias

Marque uma API usando categorias de uma das seguintes maneiras:

• Gerencie as categorias às quais uma API está marcada ao editar a API, conforme descrito abaixo.
• Gerencie as APIs marcadas com uma categoria ao editar a categoria.

Para marcar uma API em categorias ao editar a API:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Clique em .
5. Clique no campo Categorias e siga uma destas etapas:
   • Selecione uma categoria na lista suspensa.
   • Adicione uma nova categoria digitando o nome dela e pressionando Enter. A nova categoria será adicionada à página "Categorias" e disponibilizada ao adicionar ou editar outras APIs.
6. Repita o processo para incluir mais categorias na API.
7. Clique em Salvar.

Editar o título e a descrição de exibição

Para editar o título e a descrição de exibição:

1. Acesse o catálogo de APIs.
2. Clique na guia APIs se ela ainda não estiver selecionada.
3. Clique na linha da API que você quer editar.
4. Clique em .
5. Edite os campos Título de exibição e Descrição de exibição, conforme necessário.
6. Clique em Salvar.

Remover uma API do portal

Para remover uma API do seu portal:

1. Acesse o catálogo de APIs.
2. Selecione as APIs se ainda não estiverem selecionadas.
3. Posicione o cursor sobre a API na lista para exibir o menu de ações.
4. Clique em .

Gerenciar as categorias usadas para descobrir APIs relacionadas

Marque APIs usando categorias para permitir que os desenvolvedores de apps descubram APIs relacionadas na página APIs do portal ativo. Adicione e gerencie categorias, conforme descrito nas seções a seguir.

Acesse a página "Categorias"

Para acessar a página "Categorias":

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

   Como alternativa, selecione Catálogo de APIs no menu suspenso do portal, na barra de navegação superior.

3. Clique na guia Categorias.

A guia Categorias do catálogo de APIs exibe a lista das categorias que foram definidas para seu portal.

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

• Ver as categorias e as APIs com que estão marcadas
• Adicionar uma categoria
• Editar uma categoria
• Excluir uma categoria
• Gerencie as APIs publicadas no portal. Consulte Explorar o catálogo de APIs

Adicionar uma categoria

Adicione uma categoria de uma das seguintes maneiras:

• Digite o nome de uma categoria ao adicionar uma API ao portal
• Adicione manualmente uma categoria, conforme descrito abaixo

A nova categoria será adicionada à página "Categorias" e disponibilizada ao adicionar ou editar outras APIs.

Para adicionar uma categoria manualmente:

1. Acesse a página "Categorias".
2. Clique em +.
3. Digite o nome da nova categoria.
4. Opcionalmente, selecione uma ou mais APIs para marcar na categoria.
5. Clique em Criar.

Editar uma categoria

Para editar uma categoria:

1. Acesse a página "Categorias".
2. Clique em .
3. Edite o nome da categoria.
4. Adicione ou remova tags de API.
5. Clique em Salvar.

Excluir uma categoria

Quando você exclui uma categoria, todas as tags da API dessa categoria também são excluídas.

Para excluir uma categoria:

1. Acesse a página "Categorias".
2. Posicione o cursor sobre a categoria que você quer editar para exibir o menu de ações.
3. Clique em .
4. Edite o nome da categoria.
5. Adicionar ou remover APIs.
6. Clique em Salvar.

Resolver problemas com as APIs publicadas

As seções a seguir fornecem informações para ajudar a solucionar erros específicos com nossas APIs publicadas.

Erro: falha ao buscar erro retornado ao usar "testar esta API"

Ao usar essa API, 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 no documento da OpenAPI. Exemplo:

  schemes:
     - https
     - http
  

• Para erros de restrição de compartilhamento de recursos entre origens (CORS, na sigla em inglês), 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 Configurar o proxy de API para oferecer suporte a "Testar esta API".

Erro: o cabeçalho "Access-Control-Allow-Origem" contém vários valores "*, *", mas apenas um é permitido

Ao usar "Testar esta API", você poderá receber a seguinte mensagem de erro se o cabeçalho Access-Control-Allow-Origin já existir:

The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

Para corrigir esse erro, modifique a política AssignMessage para usar <Set> para definir os cabeçalhos CORS em vez de <Add>, conforme mostrado no trecho abaixo. Para mais informações, consulte o artigo relevante da comunidade.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Erro: campo de cabeçalho da solicitação não permitido

Ao usar essa API, se você receber um erro Request header field not allowed, semelhante ao exemplo abaixo, talvez seja necessário atualizar os cabeçalhos compatíveis com a política de CORS. Exemplo:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

Neste exemplo, é preciso adicionar o cabeçalho content-type à seção Access-Control-Allow-Headers na política de AssignMessage CORS, conforme descrito em Como anexar uma política Add CORS a um novo proxy de API.

Erro: acesso negado ao chamar um proxy de API usando OAuth2

A política OAuthV2 da Apigee retorna uma resposta de token que contém determinadas propriedades não compatíveis com RFC. Por exemplo, a política retornará um token com o valor BearerToken, em vez do valor esperado para RFC Bearer. Esta resposta token_type inválida pode resultar em um erro Access denied ao usar esta API.

Para corrigir esse problema, crie uma política JavaScript ou AssignMessage para transformar a saída da política em um formato compatível. Para mais informações, consulte Comportamento não compatível com o RFC.