Como publicar APIs

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Publique APIs no 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 com base no seu documento da OpenAPI ou esquema do GraphQL para permitir que os desenvolvedores de apps conheçam suas APIs. Para mais informações, consulte Sobre a documentação da API.

O que é publicado no portal?

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

• Documentos de referência de API. A interface fornecida depende de como você publica a API: usando um documento da OpenAPI ou um esquema do GraphQL. Consulte:
  • SmartDocs (OpenAPI)
  • Explorador do GraphQL
• 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. Você tem a opção de personalizar os itens a seguir:

  • Imagem exibida para cada card de API
  • Categorias usadas para inclusão de tag em APIs para permitir que os desenvolvedores descubram APIs relacionadas na página de APIs
  Observação: não é possível editar o conteúdo desta página diretamente. Ela não aparecerá na lista de páginas do seu portal. É possível editar o estilo da página ao personalizar seu tema.
  

SmartDocs (OpenAPI)

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

Observação: o console do Google Cloud é compatível com a Especificação OpenAPI 3.0 e 2.0 ao gerar documentação de Referência da API interativa usando o SmartDocs no seu portal (descrito abaixo), mas um subconjunto de recursos ainda não é compatível. As referências remotas nos documentos da OpenAPI não são compatíveis com o SmartDocs.

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

Observação: verifique se seu proxy de API está configurado para permitir solicitações pelo painel Testar esta API, conforme descrito em Como configurar seu proxy de API para ser compatível com o painel Testar esta API.

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

Observação: os exemplos de código não se destinam ao uso em ambientes de produção.

Explorador do GraphQL

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

Os desenvolvedores podem usar o GraphQL Explorer para analisar a documentação interativa baseada em esquema, criar e executar consultas, ver 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.

Sobre a documentação da API

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 durante outras fases do ciclo de vida, conforme descrito em O que acontece se eu modificar um documento?

Ao publicar sua API em um portal, salve uma versão do documento da OpenAPI ou do GraphQL para renderizar a documentação de Referência da API. Se você modificar o documento, é possível atualizar a documentação de Referência da API publicada no portal para refletir as alterações mais recentes.

Sobre URLs de callback

Quando seu aplicativos exigem um URL de callback, como ao usar o tipo de concessão de código de autorização do OAuth 2.0 (geralmente chamado de OAuth de três etapas), é possível exigir que os desenvolvedores especifiquem um URL de callback ao registrarem seus aplicativos. O URL de callback normalmente especifica o URL de um aplicativo designado para receber um código de autorização em nome do aplicativo cliente. Para mais informações, consulte Como implementar o tipo de concessão do código de autorização.

Observação: o URL de callback é armazenado como um atributo personalizado na entidade do aplicativo correspondente do console do Google Cloud. Se estiver usando um provedor de identidade de terceiros, você será responsável por sincronizar os metadados do URL de callback.

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

Ao registrar um aplicativo, os desenvolvedores precisam inserir um URL de callback para todas as APIs que precisam dele, conforme descrito em Como registrar aplicativos.

Configurar seu proxy de API para ser compatível com o painel "Testar esta API"

Observação: esta seção se aplica somente à documentação de Referência da API do SmartDocs, gerada usando um documento da OpenAPI.

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

• Adicione compatibilidade com o 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.
• Atualize a configuração do proxy de API se você estiver usando a autenticação básica ou o OAuth 2.0.

A tabela a seguir resume os requisitos de configuração do proxy de API para permitir o painel "Testar esta API" da documentação de Referência da API do 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 seguindo as etapas descritas em Como adicionar suporte ao CORS a um proxy de API.
Autenticação básica	Siga as etapas abaixo: Adicione compatibilidade com o CORS ao proxy de API. Siga as etapas descritas em Como adicionar compatibilidade com o CORS a um proxy de API. Na política "Adicionar CORS", verifique se o cabeçalho Access-Control-Allow-Headers contém o atributo authorization. Exemplo: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>
OAuth 2.0	Adicione compatibilidade com o CORS ao proxy de API. Siga as etapas descritas em Como adicionar compatibilidade com o CORS a um proxy de API. Na política "Adicionar CORS", verifique se o cabeçalho Access-Control-Allow-Headers contém 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 OAuth 2.0. Para facilitar, use a solução de amostra do OAuth 2.0 fornecida no GitHub ou execute as seguintes etapas: Verifique se o elemento <GrantType> na política do OAuth 2.0 está definido como request.formparam.grant_type (parâmetro de formulário). Para mais informações, consulte <GrantType>. Verifique se o token_type na política do OAuth 2.0 está definido como Bearer, e não como o BearerToken padrão.

Gerenciar APIs

Gerencie suas APIs conforme descrito nas próximas seções.

Ver APIs

Use o console ou o comando curl para ver as APIs que estão no seu portal.

Console

Para ver o catálogo de APIs:

1. Selecione Publicar > Portais e selecione seu portal.

2. Clique em Catálogo de APIs na página inicial do portal.
   Outra possibilidade é selecionar Catálogo de APIs no menu suspenso do portal, na barra de navegação superior.
   A guia de APIs no catálogo de APIs exibe uma lista das APIs que foram adicionadas ao seu portal.

   

   

   Como destacado na figura anterior, na guia de APIs, é possível:

   • Ver os detalhes das APIs disponíveis no seu portal
   • Adicionar uma API ao portal
   • Edite uma API no portal realizando uma ou mais das seguintes tarefas:
     • Gerenciar a documentação da API
     • Publicar ou cancelar publicação de uma API
     • Gerenciar a visibilidade de uma API
     • 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
   • Identifique rapidamente APIs órfãs em que o produto de API associado foi removido do console do Google Cloud. Depois, recrie o produto de API ou exclua a API do seu portal.

curl

Para listar APIs usando organizations.sites.apidocs/list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.

Consulte as Observações sobre paginação para ver instruções sobre como usar a paginação no payload de resposta.

Payload de resposta:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Em que:

• modified: hora em que o item do catálogo foi modificado pela última vez em milissegundos desde a época. Por exemplo, 1698165480000.
• id: o ID do item do catálogo. Por exemplo, 399668.

Observações sobre paginação:

• Tamanho da página: use pageSize para especificar o número de itens da lista que serão retornados em uma única página. O padrão é 25, e o máximo é 100. Se houver outras páginas, nextPageToken será preenchido com um token:

  curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"
  

  Substitua:

  • PAGE_SIZE pelo número de itens de lista a serem retornados em uma página. Por exemplo, 10.

  Payload de resposta:

  {
    "status": "success",
    "message": "one page of apidocs returned",
    "requestId": "918815495",
    "data": [
      {
        "siteId": "my-org-myportal",
        "title": "Hello New World",
        "description": "Simple hello new world example",
        "specId": "apigee",
        "modified": "1699146887000",
        "anonAllowed": true,
        "imageUrl": "/files/camper1.jpg?v=1695841491415",
        "id": "381054",
        "categoryIds": [
          "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
          "61c1014c-89c9-40e6-be3c-69cca3505620"
        ],
        "published": true,
        "apiProductName": "Hello New World"
      }
    ],
    "nextPageToken": "7zcqrin9l6xhi4nbrb9"
  }

• Token de página:

  Use pageToken para recuperar páginas subsequentes quando houver mais de uma:

  curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
  

  Substitua:

  • PAGE_SIZE pelo número de itens de lista a serem retornados em uma página. Por exemplo, 10.
  • PAGE_TOKEN pelo valor nextPageToken. Por exemplo, 7zcqrin9l6xhi4nbrb9.

Adicionar uma API

Observação: consulte os Limites do portal para conhecer as limitações atuais.

Para adicionar uma API ao portal:

Console

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

3. Clique em Adicionar.

   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 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
   Publicado	Selecione Publicado para publicar a API no seu portal. Desmarque a caixa de seleção se não tiver tudo pronto para publicar a API. É possível alterar a configuração mais tarde, conforme descrito em Publicar ou cancelar publicação de uma API.
   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. É possível alterar o título de exibição mais tarde, conforme descrito em Editar o título e a descrição de exibiçã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. É possível alterar a descrição de exibição mais tarde, conforme descrito em Editar o título e a descrição de exibiçã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 mais tarde, 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 Fazer upload do arquivo e faça upload de um arquivo. Clique na guia Importar de um URL e importe uma especificação fornecendo um nome e um URL da origem de importação. 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 possibilidade é selecionar Sem documentação e adicionar uma mais tarde, conforme descrito em Gerenciar a documentação da API. Observação: ao importar um documento OpenAPI usando um URL, os redirecionamentos não serão seguidos.
   Visibilidade	Se você não tiver inscrição 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 inscrição 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 poderão ver a API. É possível gerenciar a visibilidade do público-alvo mais tarde, conforme descrito em Gerenciar a visibilidade de uma API.
   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 que já existe, 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 mais tarde, conforme descrito em Gerenciar a imagem de um card de API. Ao especificar o URL de uma imagem externa, a imagem não será enviada para seus recursos. além disso, o carregamento da imagem no portal integrado estará sujeito à disponibilidade dela, que pode ser bloqueada ou restrita pelas políticas de segurança de conteúdo.
   Categorias	Marque a API com as categorias para permitir que os desenvolvedores de apps 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 é adicionada à página "Categorias" e fica disponível quando você adiciona ou edita outras APIs.

7. Clique em Salvar.

curl

Para adicionar uma API ao portal usando organizations.sites.apidocs.create:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• TITLE pelo título de exibição. Por exemplo, Hello World 2.
• DESCRIPTION pela descrição de exibição. Por exemplo, Simple hello world example.
• ANON_TRUE_OR_FALSE com true ou false (padrão), em que true permite o acesso de usuário anônimo. Essa configuração será ignorada se houver sua inscrição na versão Beta do recurso de gerenciamento de públicos-alvo.
• IMAGE_URL pelo URL de uma imagem externa usada para o item de catálogo ou um caminho de arquivo para arquivos de imagem armazenados no portal, por exemplo, /files/book-tree.jpg Ao especificar o URL de uma imagem externa, a imagem não será enviada para seus recursos. além disso,o carregamento da imagem no portal integrado estará sujeito à disponibilidade, que pode ser bloqueada ou restrita pelas políticas de segurança de conteúdo.
• CALLBACK_TRUE_OR_FALSE por true ou false (padrão), em que true exige que um usuário do portal insira um URL ao gerenciar o aplicativo.

• CATEGORY_ID pelo ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separe vários IDs de categoria com uma vírgula. Consiga o ID da categoria com o comando list API categories.

  Observação: é preciso ter categorias definidas para adicioná-las aqui. Consulte Adicionar uma categoria e Explorar categorias para ver instruções.

• PUBLISHED_TRUE_OR_FALSE por true ou false (padrão), em que true indica que a API está disponível publicamente.

• API_PRODUCT pelo nome do produto da API. Por exemplo, Hello World 2.

Payload de resposta:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Em que:

• modified: hora em que o item do catálogo foi modificado pela última vez em milissegundos desde a época. Por exemplo, 1698165480000.
• id: o ID do item do catálogo. Por exemplo, 399668.

Editar uma API

Depois de adicionar uma API, use o console ou uma chamada de API para fazer edições.

Nesta seção, apresentamos um exemplo detalhado das etapas a serem seguidas para modificar uma API que já existe no portal.

Consulte as seções seguintes para ver as configurações específicas de modificação.

Console

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 Editar.
5. Em Detalhes da API, faça as modificações. Consulte as descrições das opções em Adicionar uma API.
6. Clique em Salvar.

curl

Depois de adicionar uma API, use a chamada organizations.sites.apidocs.update para fazer edições.

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Neste exemplo, apresentamos as etapas necessárias para alterar o status publicado da API no portal de true para false. É possível alterar mais de uma configuração em uma única chamada de API, se necessário.

1. Veja uma lista das APIs no seu portal usando organizations.sites.apidocs/list para localizar o id gerado que identifica exclusivamente cada API:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

   Substitua:

   • ORG_NAME pelo nome da organização. Por exemplo, my-org.
   • SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.

   Payload de resposta:

   {
     "status": "success",
     "message": "one page of apidocs returned",
     "requestId": "1167960478",
     "data": [
       {
         "siteId": "my-org-myportal",
         "title": "Hello New World",
         "description": "Simple hello new world example",
         "specId": "hellowworld",
         "modified": "1695841621000",
         "anonAllowed": true,
         "imageUrl": "/files/camper1.jpg?v=1695841491415",
         "id": "381054",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
           "61c1014c-89c9-40e6-be3c-69cca3505620"
         ],
         "published": true,
         "apiProductName": "Hello New World"
       },
       {
         "siteId": "my-org-myportal",
         "title": "mock-product",
         "description": "Mock product",
         "specId": "apigee spec",
         "modified": "1698956849000",
         "anonAllowed": true,
         "id": "399638",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
         ],
         "published": true,
         "apiProductName": "mock-product"
       },
       {
         "siteId": "my-org-myportal",
         "title": "Hello World 2",
         "description": "Simple hello world example",
         "specId": "hello-new-world",
         "modified": "1698950207000",
         "anonAllowed": true,
         "imageUrl": "/files/book-tree.jpg?v=1698165437881",
         "id": "399668",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
           "61c1014c-89c9-40e6-be3c-69cca3505620"
         ],
         "published": true,
         "apiProductName": "Hello World 2"
       }
     ]
   }

   Em que:

   • modified: hora em que o item do catálogo foi modificado pela última vez em milissegundos desde a época. Por exemplo, 1698165480000.
   • id: o ID do item do catálogo. Por exemplo, 399668.

2. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais de uma API específica:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

   Substitua:

   • ORG_NAME pelo nome da organização. Por exemplo, my-org.
   • SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
   • API_DOC pelo id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar esse valor.

   Payload de resposta:

   {
     "status": "success",
     "message": "apidoc returned",
     "requestId": "2072952505",
     "data": {
       "siteId": "my-org-myportal",
       "title": "Hello World 2",
       "description": "Simple hello world example",
       "specId": "hello-new-world",
       "modified": "1698950207000",
       "anonAllowed": true,
       "imageUrl": "/files/book-tree.jpg?v=1698165437881",
       "id": "399668",
       "categoryIds": [
         "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
         "61c1014c-89c9-40e6-be3c-69cca3505620"
       ],
       "published": true,
       "apiProductName": "Hello World 2"
     }
   }

3. Inclua os valores mutáveis que você quer manter na chamada organizations.sites.apidocs.update e modifique os valores que você quer alterar. Se você omitir uma linha, a configuração padrão será usada. Neste exemplo, altere a configuração published de true para false:

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": "IMAGE_URL",
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": false,
           "apiProductName": "API_PRODUCT",
        }'
   

   Substitua:

   • TITLE pelo título de exibição. Por exemplo, Hello World 2.
   • DESCRIPTION pela descrição de exibição. Por exemplo, Simple hello world example.
   • ANON_TRUE_OR_FALSE com true ou false (padrão), em que true permite o acesso de usuário anônimo. Essa configuração será ignorada se houver sua inscrição na versão Beta do recurso de gerenciamento de públicos-alvo.
   • IMAGE_URL pelo URL de uma imagem externa usada para o item de catálogo ou um caminho de arquivo para arquivos de imagem armazenados no portal, por exemplo, /files/book-tree.jpg Ao especificar o URL de uma imagem externa, a imagem não será enviada para seus recursos. além disso,o carregamento da imagem no portal integrado estará sujeito à disponibilidade, que pode ser bloqueada ou restrita pelas políticas de segurança de conteúdo.
   • CALLBACK_TRUE_OR_FALSE por true ou false (padrão), em que true exige que um usuário do portal insira um URL ao gerenciar o aplicativo.
   • CATEGORY_ID pelo ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separe vários IDs de categoria com uma vírgula. Consiga o ID da categoria com o comando list API categories.
   • API_PRODUCT pelo nome do produto da API. Por exemplo, Hello World 2.

   Payload de resposta:

   {
     "status": "success",
     "message": "ApiDoc updated",
     "requestId": "197181831",
     "data": {
       "siteId": "my-org-myportal",
       "title": "Hello World 2",
       "description": "Simple hello world example.",
       "modified": "1698884328000",
       "anonAllowed": true,
       "imageUrl": "/files/book-tree.jpg",
       "id": "408567",
       "requireCallbackUrl": true,
       "categoryIds": [
         "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
         "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
       ],
       "published": PUBLISHED_TRUE_OR_FALSE,
       "apiProductName": "Hello World 2"
     }
   }

Publicar ou cancelar publicação de uma API

A publicação é o processo de disponibilização das APIs para os desenvolvedores de apps consumirem.

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

Console

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 Editar.
5. Em Detalhes da API, marque ou desmarque Publicado (listado no catálogo) para publicar ou cancelar publicação da API no seu portal, respectivamente.
6. Clique em Salvar.

curl

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Inclua uma das seguintes opções na chamada update:

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

Para editar a API:

1. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que você quer manter e modifique os valores que você quer alterar. Se você omitir uma configuração mutável, o valor padrão será usado.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Consulte Editar uma API para ver um exemplo detalhado das etapas, variáveis e do payload retornado.

Gerenciar a visibilidade de uma API

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 inscrição na versão Beta do recurso de gerenciamento de público-alvo)

  Observação: se você definir a visibilidade como Usuários autenticados ou Públicos-alvo selecionados, a API não será indexada por mecanismos de pesquisa.

Para gerenciar a visibilidade de uma API em seu portal:

Console

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

5. Selecione a configuração de visibilidade. Se você tiver inscrição na versão Beta do recurso de públicos-alvo, selecione uma das seguintes opções em Visibilidade da API:

   • Público (visível para todos) para permitir que todos os usuários vejam a página.
   • Usuários autenticados para permitir que apenas usuários registrados vejam a página.
   • Públicos-alvo selecionados para selecionar os públicos-alvo específicos que poderão ver a página. Consulte Como gerenciar os públicos-alvo do seu portal.

   Caso contrário, selecione uma das seguintes opções em Público-alvo:

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

6. Clique em Enviar.

curl

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Se você tiver inscrição na versão Beta do recurso de gerenciamento de públicos-alvo, use o console para gerenciar públicos-alvo.

Se você não tiver inscrição no recurso de gerenciamento de públicos-alvo, a visibilidade será gerenciada via anonAllowed.

Inclua uma das seguintes opções na chamada update:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Para editar a API:

1. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que você quer manter e modifique os valores que você quer alterar. Se você omitir uma configuração mutável, o valor padrão será usado.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Consulte Editar uma API para ver um exemplo detalhado das etapas, variáveis e do payload retornado.

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:

Console

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 Editar.
5. Em Detalhes da API, marque ou desmarque a opção Exigir que desenvolvedores especifiquem um URL de callback para especificar que um URL de callback é obrigatório ou não, respectivamente.
6. Clique em Salvar.

curl

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Inclua uma das seguintes opções na chamada update:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Para editar a API:

1. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que você quer manter e modifique os valores que você quer alterar. Se você omitir uma configuração mutável, o valor padrão será usado.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Consulte Editar uma API para ver um exemplo detalhado das etapas, variáveis e do payload retornado.

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:

Console

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

5. Em Detalhes da API:

   • Clique em Selecionar imagem para especificar uma imagem se nenhuma for selecionada.
   • Clique em Alterar imagem para especificar outra imagem.
   • Clique no x na imagem para removê-la.

   Ao especificar uma imagem, especifique uma imagem com um URL externo usado para o item de catálogo ou um caminho de arquivo para arquivos de imagem armazenados no portal, por exemplo, /files/book-tree.jpg: Ao especificar o URL de uma imagem externa, a imagem não será carregada nos seus recursos. Além disso, o carregamento da imagem no portal integrado estará sujeito à disponibilidade, que pode ser bloqueada ou restrita pelas políticas de segurança de conteúdo.

6. Clique em Salvar.

curl

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Inclua o texto a seguir na chamada update:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Para editar a API:

1. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que você quer manter e modifique os valores que você quer alterar. Se você omitir uma configuração mutável, o valor padrão será usado.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Consulte Editar uma API para ver um exemplo detalhado das etapas, variáveis e do payload retornado.

Marcar uma API usando categorias

O uso de categorias ajuda os desenvolvedores de apps a descobrir APIs relacionadas. Consulte também Gerenciar categorias.

Para marcar uma API com categorias:

Console

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

5. Clique no campo Categorias e realize 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 a marcação da API com outras categorias.

7. Clique em Salvar.

curl

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Inclua o texto a seguir na chamada update:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Use o comando list categories para consultar os números de IDs das categorias.

Para editar a API:

1. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que você quer manter e modifique os valores que você quer alterar. Se você omitir uma configuração mutável, o valor padrão será usado.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Consulte Editar uma API para ver um exemplo detalhado das etapas, variáveis e do payload retornado.

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

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

Console

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

curl

Atenção: a chamada de API organizations.sites.apidocs.update redefine todos os campos mutáveis para os valores padrão, se eles não forem especificados.

Inclua o texto a seguir na chamada update:

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

Para editar a API:

1. Use a chamada organizations.sites.apidocs.get para retornar os valores atuais:

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que você quer manter e modifique os valores que você quer alterar. Se você omitir uma configuração mutável, o valor padrão será usado.

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

Consulte Editar uma API para ver um exemplo detalhado das etapas, variáveis e do payload retornado.

Remover uma API

Para remover uma API do seu portal:

Console

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

curl

Para remover uma API do seu portal via organizations.sites.apidocs.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• API_DOC pelo id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar esse valor.

Payload de resposta:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

Gerenciar a documentação da API

As seções a seguir descrevem como atualizar, fazer o download ou remover a documentação da API.

Atualizar documentação da API

Depois de publicar sua API, é possível fazer upload de uma nova versão do documento da OpenAPI ou do GraphQL a qualquer momento.

Para fazer upload de uma versão diferente da documentação da API:

Console

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 Editar.
5. No painel Documentação da API, selecione uma das seguintes opções:
   • Documento da OpenAPI
   • Esquema do GraphQL
6. Clique em Selecionar documento e escolha a versão mais recente.
7. Para o GraphQL, especifique o URL do endpoint.
8. Clique em Salvar.

curl

Para atualizar o conteúdo da documentação da OpenAPI ou do GraphQL via organizations.sites.apidocs.updateDocumentation:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• API_DOC pelo id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar esse valor.
• DISPLAY_NAME pelo nome de exibição da documentação da API. Por exemplo, Hello World 2.
• CONTENTS pela string de conteúdo codificada em base64 da documentação da API. A maioria dos ambientes de desenvolvimento contém um utilitário de conversão base64. Além disso, há muitas ferramentas de conversão on-line.

Payload de resposta:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• API_DOC pelo id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar esse valor.
• DISPLAY_NAME pelo nome de exibição da documentação da API. Por exemplo, Hello World 2.
• ENDPOINT_URI pelo nome de domínio do URI do endpoint. Por exemplo, https://demo.google.com/graphql.
• CONTENTS pela string de conteúdo codificada em base64 da documentação da API. A maioria dos ambientes de desenvolvimento contém um utilitário de conversão base64. Além disso, há muitas ferramentas de conversão on-line.

Payload de resposta:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

Observação: o conteúdo da especificação ou do esquema não é preenchido na resposta. Use a chamada organizations.sites.apidocs.getDocumentation para recuperar o conteúdo.

A documentação de Referência da API é renderizada com base no documento e adicionada à página de APIs do portal ativo.

Fazer o download da documentação da API

Depois de publicar a API, é possível fazer o download da documentação de referência da OpenAPI ou do GraphQL publicada no seu portal a qualquer momento.

Para fazer o download da documentação da API via organizations.sites.apidocs.getDocumentation:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.

• API_DOC pelo id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar esse valor.

  Payload de resposta:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Em que:

contents: a string de conteúdo codificada em base64 da documentação da API.

Dica: os usuários autorizados do portal podem fazer o download da documentação da API pelo portal:

1. Navegue até o portal.
2. Clique em APIs na barra de navegação superior. A página APIs é exibida.
3. Clique em um cartão de API para visualizar a documentação de referência da API. A documentação de Referência da API é exibida.
4. Clique em Fazer o download das especificações.

Remover documentação da API

Para remover a documentação da API:

Console

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 Editar.
5. No painel Documentação da API, selecione Sem documentação.
6. Clique em Salvar.

curl

Para remover o conteúdo do documento da API usando uma API, apague as configurações atuais enviando um corpo da solicitação vazio.

Para enviar um corpo da solicitação vazio e apagar o conteúdo atual via organizations.sites.apidocs.updateDocumentation:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• API_DOC pelo id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar esse valor.

Payload de resposta:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Gerenciar categorias

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

Explorar categorias

Use o console ou o comando curl para ver as categorias.

Console

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.
   Outra possibilidade é selecionar 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, na página de APIs, é possível:

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

curl

Para listar categorias via organizations.sites.apicategories.list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.

Payload de resposta:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Em que:

• id: o ID do item da categoria. Por exemplo, 61c1014c-89c9-40e6-be3c-69cca3505620.

Adicionar uma categoria

Para adicionar uma categoria, faça o seguinte:

Console

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

curl

Para adicionar uma categoria via organizations.sites.apicategories.create:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• CATEGORY_NAME pelo nome da categoria. Por exemplo, demo-backend.

Payload de resposta:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Editar uma categoria

Para editar uma categoria:

Console

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 Editar.
4. Edite o nome da categoria.
5. Adicione ou remova tags de API.
6. Clique em Salvar.

curl

Para editar uma categoria via organizations.sites.apicategories.patch:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• CATEGORY_ID pelo ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Consiga o ID da categoria com o comando list API categories.
• CATEGORY_NAME pelo nome da categoria. Por exemplo, demo-backend.

Payload de resposta:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

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:

Console

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 Excluir.
4. Clique em Excluir para confirmar.

curl

Para excluir uma categoria via organizations.sites.apicategories.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Substitua:

• ORG_NAME pelo nome da organização. Por exemplo, my-org.
• SITE_ID pelo nome do portal, no formato ORG_NAME-PORTAL_NAME, em que ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para apenas letras minúsculas e sem espaços nem traços. Por exemplo, my-org-myportal.
• CATEGORY_ID pelo ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Consiga o ID da categoria com o comando list API categories.

Payload de resposta:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

Resolver problemas com as APIs publicadas

Observação: esta seção se aplica somente à documentação de Referência da API do SmartDocs, gerada usando um documento da OpenAPI.

As próximas seções contêm informações para ajudar a corrigir erros específicos em nossas APIs publicadas.

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

Ao usar Testar esta API, se o erro TypeError: Failed to fetch for retornado, considere as seguintes possíveis causas e resoluções:

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

  schemes:
     - https
     - http
  

• Em erros de restrição do 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: campo de cabeçalho da solicitação não permitido

Ao usar Testar esta API, se você encontrar 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 do CORS. Exemplo:

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 AssignMessage do 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 o OAuth 2.0

A política OAuthV2 do console do Google Cloud retorna uma resposta de token que contém determinadas propriedades que não compatíveis com RFC. Por exemplo, a política retornará um token com o valor BearerToken, no lugar do valor esperado Bearer compatível com RFC. Essa resposta token_type inválida pode resultar em um erro Access denied ao usar "Testar 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.