O blog da AWS

Melhore a descoberta de APIs com o novo Amazon API Gateway Portal

Por Giedrius Praspaliauskas, Sr SSA, Serverless.

O Amazon API Gateway agora oferece um recurso de portal totalmente gerenciado, o Amazon API Gateway Portal, que elimina a necessidade de sites estáticos, soluções de código aberto ou ofertas de terceiros, que frequentemente levavam a um gerenciamento fragmentado do ciclo de vida da API e custos aumentados. O API Gateway Portal se integra ao serviço API Gateway e oferece recursos como produtos de API, funcionalidade interativa “Experimente”, e documentação para seu portfólio de APIs.

Esta solução totalmente gerenciada atende à necessidade de uma maneira integrada de apresentar APIs e ajudar desenvolvedores a encontrar, experimentar e integrar rapidamente com elas. Ao fornecer uma solução gerenciada que gerencia a infraestrutura, segurança e escalabilidade, os provedores de API podem se concentrar em criar APIs valiosas e oferecer uma ótima experiência ao desenvolvedor.

Nesta publicação, mostraremos como você pode usar o novo recurso de portal para criar portais personalizáveis com recursos de segurança aprimorados em minutos, com APIs de múltiplas contas, sem gerenciar nenhuma infraestrutura.

Visão geral

Um portal de desenvolvedor é uma página web onde provedores de API podem compartilhar suas APIs e documentação de API agrupando-as em produtos de portal. Cada produto de portal é um agrupamento lógico de APIs REST e contém a documentação que você cria e publica para seus consumidores de API. As páginas de produtos dentro de um portal contêm a documentação personalizada no nível do produto de portal. As páginas de endpoints REST do produto contêm a documentação para cada uma das APIs REST com os detalhes do caminho e método de uma API REST e o estágio em que está implantada. A combinação de páginas de Produtos e páginas de endpoints REST do Produto fornece a documentação completa para nossos consumidores de API sobre como começar a usar suas APIs REST.

Esta abstração permite que você organize endpoints de múltiplas APIs e estágios em ofertas de produtos coerentes para seus consumidores. Por exemplo, se você opera múltiplas APIs que suportam um serviço de adoção de animais de estimação, você pode criar um produto de portal “AdoptAnimals” que agrupa endpoints relacionados a cães de uma API com endpoints relacionados a gatos de outra API, enquanto organiza funções de gerenciamento de usuários em um produto de portal separado “AdoptProcess”.

Com essa flexibilidade, você pode apresentar suas APIs de uma forma que corresponda à sua lógica de negócios em vez de sua arquitetura técnica e organizar suas APIs de maneiras que façam mais sentido para seus consumidores. Para grandes empresas que gerenciam extensos portfólios de API, o API Gateway Portal oferece catálogos centralizados de APIs entre grupos de negócios, reduzindo trabalho duplicado e melhorando a padronização.

O recurso de portal cria automaticamente portais de desenvolvedor que exibem APIs com documentação, capacidades de teste interativo e análises de consumidores integradas. A plataforma usa o AWS Resource Access Manager (RAM) para compartilhamento de API entre contas, o Amazon Cognito para controle de acesso e o Amazon CloudWatch para monitoramento centralizado.

Principais recursos do API Gateway Portal

O API Gateway Portal fornece funcionalidade abrangente tanto para provedores quanto para consumidores de API.

A seguir está uma lista dos principais recursos que foram introduzidos pelo serviço no lançamento:

Experiência de portal personalizável: Você controla a marca do seu portal através de logotipos personalizados e esquemas de cores. Você pode configurar nomes de domínio personalizados com certificados SSL gerenciados pelo AWS Certificate Manager, ou usar a estrutura de domínio padrão fornecida pela AWS.

Controle de acesso flexível: O acesso aos portais de desenvolvedor pode ser controlado usando o Amazon Cognito, você pode configurar portais para serem publicamente acessíveis ou exigir autenticação. A integração com user pools do Cognito fornece gerenciamento de identidade e acesso seguro e escalável de nível empresarial, econômico e personalizável. Para organizações que usam sistemas de identidade existentes, o Cognito suporta federação com provedores de identidade SAML e OpenID Connect.

Organização de API entre contas: O portal suporta o compartilhamento de produtos de portal entre contas AWS usando o AWS RAM, para que as organizações possam criar um catálogo de API unificado mantendo flexibilidade para os provedores de API desenvolverem e manterem APIs em suas próprias contas. Quando você compartilha um produto de portal com outra conta, essa conta não pode modificar nenhuma propriedade do seu produto de portal ou páginas de endpoint de produto, então os provedores de API mantêm controle sobre suas APIs enquanto ainda permitem a descoberta em toda a organização. As capacidades de compartilhamento entre contas fornecem benefícios significativos de governança para clientes empresariais, incluindo descoberta centralizada, padronização, redução de duplicação, propriedade clara e acesso controlado.

Documentação: Além da documentação de referência da API sincronizada a partir de suas definições de API, você pode adicionar documentação suplementar incluindo guias, casos de uso e exemplos de integração.

Pesquisa, descoberta e exploração interativa de API: Os consumidores podem pesquisar em todo o seu catálogo. O portal fornece navegação intuitiva e personalizável e organização para ajudar os usuários a encontrar os endpoints certos para suas necessidades. Usando a funcionalidade “Experimente”, os consumidores podem testar APIs diretamente do portal. Os usuários podem inserir parâmetros de solicitação, cabeçalhos e ver respostas ao vivo, reduzindo o time to value para integrações de API. Este ambiente inclui limites integrados para segurança e controle de custos.

Controle de acesso e governança

O Amazon API Gateway Portal fornece capacidades de segurança e governança essenciais para implantações de produção.

Gerenciamento de identidade e acesso: A integração com user pools do Cognito fornece gerenciamento de identidade e acesso seguro e escalável de nível empresarial, econômico e personalizável, incluindo autenticação multifator, políticas de senha e gerenciamento do ciclo de vida do usuário.

Autorização de API: O portal respeita os mecanismos de autorização existentes configurados em suas APIs, incluindo AWS IAM, autorizadores Lambda e user pools do Cognito. O acesso ao portal não ignora seus controles de segurança estabelecidos.

Governança entre contas: Ao compartilhar produtos de portal entre contas usando o AWS RAM, os proprietários originais da API mantêm controle total sobre seus endpoints, incluindo estratégias de autorização, configurações de integração e configurações de estágio. Os proprietários de portais podem usar produtos de portal compartilhados, mas não podem modificar as configurações subjacentes da API.

Auditoria e monitoramento: Todas as atividades de gerenciamento de portal se integram ao AWS CloudTrail para registro de auditoria abrangente. Você pode usar o Amazon CloudWatch RUM para realizar monitoramento de usuários reais para coletar e visualizar análises sobre consumidores de API em tempo quase real.

Limites de recursos: O serviço inclui cotas integradas para prevenir abuso, incluindo limites de taxa de teste de API, tamanhos de payload e tempos limite de integração. Com esses limites, a funcionalidade “Experimente” não pode impactar o desempenho da sua API de produção.

Primeiros passos

Configurar um portal envolve três etapas principais: criar produtos de portal, configurar o portal e publicar para acesso do consumidor. Vamos percorrer essas etapas em mais detalhes.

Criar produto de portal

O procedimento a seguir mostra como criar um produto de portal:

  1. Navegue até o console do API Gateway e selecione Produtos de portal na navegação principal.
  2. Escolha Criar produto de portal e especifique os detalhes do seu produto de portal, incluindo nome, descrição e configurações de visibilidade.
  3. Em seguida, selecione os endpoints que você deseja incluir neste produto de portal. Você pode escolher estágios inteiros de API ou recursos e métodos específicos, e até renomear endpoints com nomes amigáveis para melhor descoberta.
  4. O sistema importa automaticamente sua documentação de API. Você pode melhorar a documentação com contexto adicional, casos de uso e exemplos posteriormente.
  5. Organize os endpoints de produtos em categorias personalizadas que refletem sua lógica de negócios em vez de detalhes de implementação técnica.

Configurar o portal de desenvolvedor

O procedimento a seguir mostra como criar um portal.

  1. Selecione Portais de desenvolvedor na navegação do console do API Gateway.
  2. Especifique o nome do seu portal, descrição e configuração de domínio.
  3. Escolha entre adicionar seu prefixo ao domínio AWS padrão ou configurar um nome de domínio personalizado com seu próprio certificado SSL.
  4. Configure o controle de acesso selecionando requisitos de autenticação. Para portais internos, você pode exigir autenticação do Amazon Cognito, enquanto portais públicos podem permitir acesso anônimo à documentação.
  5. Carregue seu logotipo e selecione temas de cores para corresponder à identidade da sua marca.
  6. Adicione seus produtos de portal. Você pode incluir produtos da sua conta ou produtos compartilhados com você de outras contas através do AWS RAM. O portal fornece capacidades de pesquisa e filtragem para consumidores.

Visualizar e publicar

Antes de tornar seu portal publicamente disponível, use a funcionalidade de visualização para revisar a experiência do consumidor. A visualização mostra exatamente como seu portal aparecerá para os usuários, incluindo navegação, documentação e capacidades de teste de API disponíveis.

Quando estiver satisfeito com a configuração, escolha Publicar portal para torná-lo acessível aos consumidores. O processo de publicação normalmente leva alguns minutos, e o API Gateway fornece a URL final do portal para distribuição aos seus consumidores.

Conclusão e próximos passos

O novo API Gateway Portal elimina a complexidade de construir e manter sites personalizados de documentação de API. Seus desenvolvedores obtêm uma experiência profissional e rica em recursos onde podem descobrir e experimentar suas APIs imediatamente. Além disso, como tudo permanece dentro da AWS, você obtém segurança integrada, operações simplificadas e observabilidade abrangente através da integração com serviços como CloudWatch e CloudTrail.

Pronto para simplificar sua experiência de descoberta de API? Veja como começar:

Este conteúdo foi traduzido do post original do blog, que pode ser encontrado aqui.

Autores

Giedrius Praspaliauskas, Sr SSA, Serverless

Tradutores

Rodrigo Peres é Arquiteto de Soluções na AWS, com mais de 20 anos de experiência trabalhando com arquitetura de soluções, desenvolvimento de sistemas e modernização de sistemas legados.

Daniel Abib é arquiteto de soluções sênior na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e segurança. Ele trabalha apoiando clientes corporativos, ajudando-os em sua jornada para a nuvem.

https://www.linkedin.com/in/danielabib/