Introdução

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

As seções a seguir apresentam a você os produtos de API e os principais conceitos relacionados.

O que é um produto de API?

Como provedor de API, você cria produtos de API para agrupar suas APIs e disponibilizá-las para o consumo dos desenvolvedores de apps. Pense nos produtos de API como sua linha de produtos.

Especificamente, um produto da API agrupa o seguinte:

  • Coleção de recursos da API (URIs)
  • Plano de serviços
  • Metadados específicos da sua empresa para monitoramento ou análise (opcional)

Os recursos de API incluídos em um produto de API podem vir de uma ou mais APIs, para que você possa combinar recursos para criar conjuntos de recursos especializados, conforme mostrado na figura a seguir.

É possível criar vários produtos de API para solucionar casos de uso que atendem a necessidades específicas. Por exemplo, é possível criar um produto de API que agrupe vários recursos de mapeamento para permitir que os desenvolvedores integrem facilmente mapas nos seus aplicativos. Além disso, é possível definir propriedades diferentes em cada produto de API, como diferentes níveis de preços. Por exemplo, é possível oferecer as seguintes combinações de produtos de API:

  • Um produto de API que oferece um limite de acesso baixo, como 1.000 solicitações por dia, por um preço com desconto. Um segundo produto de API que fornece acesso aos mesmos recursos, mas com um limite de acesso maior e um preço mais alto.
  • Um produto de API sem custo financeiro que oferece acesso somente leitura a recursos. Um segundo produto de API que fornece acesso de leitura/gravação aos mesmos recursos por uma pequena taxa.

Além disso, é possível controlar o acesso aos recursos da API em um produto. Por exemplo, você pode agrupar recursos que podem ser acessados apenas por desenvolvedores internos ou somente por clientes pagantes.

Os produtos de API são o principal mecanismo para autorização e controle de acesso às suas APIs. Na Apigee, as chaves de API são provisionadas, não para as próprias APIs, mas para produtos de API. Em outras palavras, as chaves de API são provisionadas para pacotes de recursos com um plano de serviços anexado.

Para acessar seus produtos de API, os desenvolvedores de aplicativo registram os aplicativos deles, conforme descrito em "Como registrar aplicativos". Quando um aplicativo tenta acessar um produto de API, a autorização é aplicada pela Apigee no ambiente de execução para garantir que:

  • o app solicitante tenha permissão para acessar um determinado recurso da API;
  • O app solicitante não excedeu a cota permitida;
  • se definidos, os escopos do OAuth estabelecidos no produto da API correspondam aos associados ao token de acesso apresentado pelo app.

Entenda os principais conceitos

Analise os seguintes conceitos principais antes de criar seus produtos de API.

Chaves de API

Quando você registra um app de desenvolvedor na sua organização, o app precisa estar associado a pelo menos um produto de API. Ao parear um app com um ou mais produtos de API, o Edge atribui uma chave do consumidor exclusiva.

A chave de consumidor ou o token de acesso funciona como credenciais de solicitação. O desenvolvedor do app incorpora a chave do consumidor no aplicativo para que, quando o aplicativo fizer uma solicitação a uma API hospedada pelo Edge, o aplicativo transmitirá a chave do consumidor na solicitação de uma das seguintes maneiras:

  • Quando a API usa a verificação de chaves de API, o app precisa transmitir a chave do consumidor diretamente.
  • Quando a API usa a verificação de token OAuth, o app precisa transmitir um token derivado da chave do consumidor.

A aplicação da chave de API não acontece automaticamente. Usando a chave do cliente ou os tokens OAuth como credenciais de solicitação, o proxy de API valida as credenciais de solicitação nos proxies de API incluindo uma política VerifyAPIKey ou uma política OAuth/VerifyAccessToken, no fluxo apropriado. Se você não incluir uma política de aplicação de credenciais no Proxy de API, qualquer autor da chamada poderá invocar suas APIs. Para mais informações, consulte Verificar a política de chaves de API.

Para verificar as credenciais transmitidas na solicitação, o Edge executa as seguintes etapas:

  • Recebe as credenciais transmitidas com a solicitação. No caso da verificação de token OAuth, o Edge verifica se o token não expirou e pesquisa a chave do consumidor usada para gerar o token.
  • Recupere a lista de produtos de API a que a chave do consumidor foi associada.
  • Confirme se o proxy da API atual está incluído no produto da API e se o caminho do recurso atual (caminho do URL) está ativado no produto da API.
  • Verifique se a chave do consumidor não expirou ou foi revogada. Confira também se o app não está revogado e se o desenvolvedor está ativo.

Se todas as verificações acima forem aprovadas, a verificação de credencial será bem-sucedida.

Em resumo, o Edge gera automaticamente chaves do consumidor, mas os editores de API precisam aplicar a verificação de chaves nos proxies da API usando políticas adequadas.

Aprovação automática x manual

Por padrão, todas as solicitações para conseguir uma chave para acessar um produto de API de um app são aprovadas automaticamente. Outra opção é configurar o produto de API para aprovar as chaves manualmente. Nesse caso, você precisará aprovar as solicitações principais de qualquer app que adicione o produto de API. Para mais informações, consulte Registrar aplicativos e gerenciar chaves de API.

Cotas

As cotas podem proteger os servidores de back-end para tráfego intenso e diferenciar a linha de produtos. Por exemplo, talvez você queira agrupar recursos com uma cota alta como um produto premium e usar o mesmo pacote com uma cota menor como produto básico. Com uma cota, é possível evitar que os servidores sejam sobrecarregados se um produto for conhecido e receber muitas solicitações.

Para informações sobre como configurar a cota, consulte Política de cotas. Para informações sobre como usar as configurações de cota dos produtos nas políticas de cota, consulte este artigo da comunidade: Como as configurações de cota em um produto de API interagem com as políticas de cotas em um proxy de API?.

Escopos do OAuth

Como um nível adicional de segurança, é possível definir todos os escopos do OAuth, como uma lista separada por vírgulas, que precisa estar presente nos tokens de acesso enviados pelo produto. Ao criar um produto, é preciso conhecer todos os escopos da organização. Os escopos adicionados a um produto precisam corresponder aos escopos atuais, caso contrário, o produto não será seguro.

Saiba mais sobre o uso de escopos com políticas de OAuth do Edge em Como trabalhar com escopos do OAuth2.

Níveis de acesso

Ao definir um produto de API, é possível configurar os níveis de acesso a seguir.

Nível de acesso Descrição
Público Produtos de API disponíveis para todos os desenvolvedores. Você pode adicioná-los aos portais do desenvolvedor integrados ou baseados em Drupal.
Particular ou somente interno

Produtos de API criados para uso particular ou interno.

Observação: não há diferença funcional entre os níveis de acesso "Particular" e "Somente interno". Escolha o rótulo que melhor descreve o público-alvo do produto de API.

Para o portal integrado, é possível adicionar produtos de API privados ou internos e disponibilizá-los a desenvolvedores de apps, conforme necessário.

Para portais de desenvolvedores baseados em Drupal, é possível gerenciar o acesso a produtos de API particulares ou internos apenas no seu portal do desenvolvedor, conforme descrito nas seguintes seções:

  • Para portais de desenvolvedores do Drupal 9, é possível configurar o acesso a produtos de API particulares ou internos apenas no seu portal, conforme descrito em Configurar permissões de acesso a produtos de API.
  • Para os portais do desenvolvedor Drupal 7, não é possível adicionar produtos de API Privados ou Somente internos ao portal do desenvolvedor. Para disponibilizar produtos de API particulares ou internos para desenvolvedores de apps, adicione-os manualmente a um app registrado pela interface ou API de gerenciamento do Edge, conforme descrito em Registrar apps e gerenciar chaves de API. Depois de adicionado, o desenvolvedor verá o produto de API associado ao aplicativo no seu portal, conforme descrito em Como gerenciar produtos de API em um aplicativo. Se o desenvolvedor do app desativar o acesso a um produto de API interno ou privado, ele será removido do app e precisará ser adicionado manualmente pelo administrador do portal.