Como publicar APIs

Você está vendo a documentação da Apigee X.
Ver a documentação da Apigee Edge.

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

O que é publicado no portal?

Quando você publica uma API, as seguintes atualizações são feitas automaticamente no seu portal:
  • A documentação de referência da API SmartDocs foi adicionada ao seu portal

    A documentação de referência da API SmartDocs é renderizada a partir de um snapshot de uma especificação da OpenAPI. A IU do SmartDocs é baseada em Angular Material, uma biblioteca de componentes de IU de última geração.

    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 na especificação OpenAPI. Para OAuth, os seguintes fluxos são compatíveis: código de autorização, implícito, senha e credenciais do cliente.

    Página de documentação de referência da API com destaques que mostram como autorizar sua chamada de API, desafixar o painel "Testar esta API", fazer o download de especificações relevantes e executar a API.

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

    Expandir painel "Testar esta API"

  • Um link para a página "Referência da API" foi adicionado à página "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 marcar APIs para permitir que os desenvolvedores descubram APIs relacionadas na página de APIs

    Página de APIs no portal ativo mostrando duas categorias e o uso das imagens

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 renderizar 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ções, poderá tirar outro instantâneo da especificação para refletir as alterações mais recentes na documentação de referência da API.

A Apigee é compatível com a OpenAPI Specification 3.0 quando você gera documentação de referência interativa da API usando o SmartDocs em seu portal (descrito abaixo), embora um subconjunto de recursos ainda não seja compatível. Para mais informações, consulte Problemas conhecidos com o portal integrado.

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 Como 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 Como registrar apps.

Como configurar o proxy de API para suportar o painel "Testar esta API"

Antes de publicar suas APIs, você precisará configurar o proxy de sua API para permitir a realização de solicitações no painel "Testar esta API" da documentação de referência da API SmartDocs, da seguinte maneira:

  • Adicione suporte a CORS aos proxies de API para aplicar solicitações de origem cruzada 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 comumente 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 as etapas abaixo:
  1. 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.
  2. 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
  1. 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.
  2. 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>
  3. 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 token_type na política do OAuth2 está definida como Bearer, e não como BearerToken padrão.

Como explorar 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.

Guia de APIs que mostra informações sobre as APIs, incluindo nome, descrição, visibilidade, categorias, especificação associada e horário da última modificação

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

Como 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 no portal:

    Campo Descrição
    PublicadaSelecione Publicado para publicar a API no seu portal. Desmarque a caixa de seleção se você não estiver pronto para publicar a API. É possível alterar a configuração mais tarde, conforme descrito em Como publicar ou cancelar a publicação de uma API no 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 Como 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 Como editar título e descrição.
    Exigir que os desenvolvedores especifiquem um URL de callbackAtive 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 Como gerenciar o URL de callback para uma API.
    Especificações da API de origem Selecione a origem a ser usada no snapshot. Selecione Selecionar uma especificação OpenAPI para selecionar ou fazer upload de uma especificação. Como alternativa, é possível selecionar Nenhuma documentação da API e incluir uma depois de adicionar a API, conforme descrito em Como gerenciar o snapshot da especificação.
    Visibilidade

    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 posteriormente, conforme descrito em Como gerenciar a visibilidade de uma API no seu portal.

    Imagem de produto de API 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 posteriormente, conforme descrito em Como 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 Save.

Como gerenciar o snapshot da especificação

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

Para gerenciar o snapshot da especificação OpenAPI:

  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:
    Ícone e mensagem indicando snapshot desatualizado
  5. Clique em ícone de edição.
  6. Execute uma das seguintes tarefas:
    • Para atualizar um snapshot que está desatualizado, clique em Atualizar snapshot.
    • Para alterar a especificação OpenAPI usada para gerar a documentação da API, selecione Selecionar uma especificação OpenAPI na lista suspensa de especificações da API de origem para selecionar, fazer upload ou importar uma nova especificação.
  7. Clique em Save.

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

Ícone e mensagem indicam que o snapshot é atual

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

Para publicar ou cancelar a 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 Ícone &quot;Editar&quot;.
  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 Save.

Gerenciar a visibilidade de uma API em seu portal

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

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 Ícone &quot;Editar&quot;.
  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.
    Selecione uma destas 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.

Como 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 Ícone &quot;Editar&quot;.
  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 Save.

Como 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 Ícone &quot;Editar&quot;.
  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 Save.

Como 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 Ícone &quot;Editar&quot;.
  5. Clique no campo Categorias e execute uma das seguintes 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 para marcar a API a outras categorias.
  7. Clique em Save.

Como 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 Ícone &quot;Editar&quot;.
  5. Edite os campos Título de exibição e Descrição de exibição, conforme necessário.
  6. Clique em Save.

Como remover uma API do portal

Para remover uma API do seu portal, siga estas etapas:

  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 Ícone &quot;Editar&quot;.

Como gerenciar 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.

Como explorar a página "Categorias"

Para ver 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.

Guia &quot;Categorias&quot; que mostra o nome das categorias, bem como o nome e o número total de APIs atribuídas

Conforme destacado na figura anterior, a página de APIs permite que você:

Como adicionar uma categoria

Adicione uma categoria de uma das seguintes maneiras:

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.

Como 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 Save.

Como 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. Adicione ou remova APIs.
  6. Clique em Save.

Solução de problemas com suas 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 na especificação 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 Como configurar seu proxy de API para ser compatível com o painel "Teste esta API".

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

Ao usar essa 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 Erro de CORS: cabeçalho contém vários valores '*, *', mas apenas um é permitido.

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