Práticas recomendadas para o design e o desenvolvimento de proxies de API com o Apigee

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Este documento fornece um conjunto de práticas recomendadas para desenvolver proxies de API com o Apigee.

Os tópicos abordados aqui incluem design, programação, utilização de políticas, monitorização e depuração. As informações foram recolhidas com base na experiência de programadores que trabalham com o Apigee para implementar programas de API bem-sucedidos. Este é um documento dinâmico e vai ser atualizado periodicamente.

Além das diretrizes aqui apresentadas, também pode considerar útil o artigo Introdução aos antipadrões.

Normas de desenvolvimento

Comentários e documentação

• Forneça comentários inline nas configurações ProxyEndpoint e TargetEndpoint. Os comentários melhoram a legibilidade de um fluxo, especialmente quando os nomes dos ficheiros de políticas não são suficientemente descritivos para expressar a funcionalidade subjacente do fluxo.
• Torne os comentários úteis. Evite comentários óbvios.
• Use recuos, espaçamentos, alinhamentos verticais, etc., consistentes.

Programação ao estilo de framework

A programação ao estilo de framework envolve o armazenamento de recursos de proxy de API no seu próprio sistema de controlo de versões para reutilização em ambientes de desenvolvimento locais. Por exemplo, para reutilizar uma política, armazene-a no controlo de origem para que os programadores possam sincronizá-la e usá-la nos respetivos ambientes de desenvolvimento de proxy.

• Para ativar o princípio DRY (não se repita), sempre que possível, as configurações de políticas e os scripts devem implementar funções especializadas e reutilizáveis. Por exemplo, uma política dedicada para extrair parâmetros de consulta de mensagens de pedidos pode ser denominada ExtractVariables.ExtractRequestParameters.
• Limpe as políticas e os recursos não usados (JavaScript, Java, XSLT) dos proxies de API, especialmente os recursos grandes que têm o potencial de abrandar os procedimentos de importação e implementação.

Convenções de nomenclatura

• O atributo name da política e o nome do ficheiro de política XML têm de ser idênticos.
• O atributo name da política de script e da política ServiceCallout e o nome do ficheiro de recursos devem ser idênticos.
• DisplayName deve descrever com precisão a função da política a alguém que nunca trabalhou com esse proxy de API.
• Atribua nomes às políticas de acordo com a respetiva função. A Apigee recomenda que estabeleça uma convenção de nomenclatura consistente para as suas políticas. Por exemplo, use prefixos curtos seguidos de uma sequência de palavras descritivas separadas por traços. Por exemplo, AM-xxx para a política AssignMessage. Veja também a ferramenta apigeelint.
• Use as extensões adequadas para ficheiros de recursos: .js para JavaScript, .py para Python e .jar para ficheiros JAR Java.
• Os nomes das variáveis devem ser consistentes. Se escolher um estilo, como camelCase ou under_score, use-o em todo o proxy da API.
• Sempre que possível, use prefixos de variáveis para organizar as variáveis com base na respetiva finalidade, por exemplo, Consumer.username e Consumer.password.

Desenvolvimento de proxy de API

Considerações de design iniciais

Aviso: não chame a API Apigee a partir de proxies de API. A API é usada para fins de gestão administrativa e não para a lógica do fluxo da API. Devido às entradas de cache de maior duração nos servidores da API Apigee, pode não ver os dados atualizados imediatamente nos fluxos do proxy, especialmente se estiver a fazer gravações rápidas e, em seguida, leituras. As soluções alternativas de programação para este comportamento podem afetar o desempenho dos seus proxies.

Em alternativa, use políticas em proxies de API.

• Para orientações sobre a criação de APIs RESTful, transfira o livro eletrónico Web API Design: The Missing Link.
• Tire partido das políticas e da funcionalidade do Apigee sempre que possível para criar proxies de API. Evite codificar toda a lógica de proxy em recursos JavaScript, Java ou Python.
• Construir fluxos de forma organizada. É preferível ter vários Flows, cada um com uma única condição, em vez de vários anexos condicionais ao mesmo PreFlow e Postflow.
• Como "salvaguarda", crie um proxy de API predefinido com um BasePath de ProxyEndpoint de /. Isto pode ser usado para redirecionar pedidos de API base para um site de programadores, para devolver uma resposta personalizada ou realizar outra ação mais útil do que devolver o messaging.adaptors.http.flow.ApplicationNotFound predefinido.
• Para um desempenho ideal, a Apigee recomenda que não use mais de 3000 basepaths de proxy de API por ambiente do Apigee ou grupo de ambientes. Exceder esta recomendação pode resultar num aumento da latência para todas as implementações de proxy de API novas e existentes.
• Use recursos TargetServer para desassociar as configurações de TargetEndpoint de URLs concretos, suportando a promoção em vários ambientes.
  Consulte o balanceamento de carga nos servidores de back-end.
• Se tiver várias RouteRules, crie uma como "predefinição", ou seja, como uma RouteRule sem condição. Certifique-se de que a RouteRule predefinida é definida por último na lista de rotas condicionais. As RouteRules são avaliadas de cima para baixo no ProxyEndpoint. Consulte a referência de configuração do proxy da API.
• Tamanho do pacote do proxy de API: os pacotes do proxy de API não podem ter mais de 15 MB.
• Controlo de versões da API: para conhecer as opiniões e as recomendações da Apigee sobre o controlo de versões da API, consulte a secção Controlo de versões no livro eletrónico Web API Design: The Missing Link.

Ativar CORS

Antes de publicar as suas APIs, tem de adicionar a política CORS ao request PreFlow do ProxyEndpoint para suportar pedidos de origem cruzada do lado do cliente.

A partilha de recursos de origem cruzada (CORS) é um mecanismo padrão que permite que as chamadas JavaScript XMLHttpRequest (XHR) executadas numa página Web interajam com recursos de domínios não originais. A CORS é uma solução implementada frequentemente para a política de mesma origem que é aplicada por todos os navegadores. Por exemplo, se fizer uma chamada XHR à API Twitter a partir de código JavaScript em execução no seu navegador, a chamada falha. Isto deve-se ao facto de o domínio que publica a página no seu navegador não ser o mesmo que o domínio que publica a API Twitter. O CORS oferece uma solução para este problema, permitindo que os servidores optem por partilhar recursos de origem cruzada.

Para obter informações sobre como ativar a CORS nos seus proxies de API antes de publicar as APIs, consulte o artigo Adicionar suporte CORS a um proxy de API.

Nota: a maioria dos navegadores modernos suporta CORS. Pode encontrar uma lista abrangente dos navegadores suportados aqui. Para uma descrição detalhada do CORS, consulte a recomendação do W3C sobre a partilha de recursos de origem cruzada.

Se estiver a usar uma política de cache no seu proxy de API, tem de garantir que a resposta da política de CORS não é armazenada em cache.

Tamanho do payload da mensagem

O tamanho da carga útil da mensagem nos fluxos de pedidos ou respostas para o Apigee está restrito por predefinição a 10 MB. Os utilizadores que precisam de processamento de payloads grandes podem configurar um limite mais elevado através do elemento <Properties> nas configurações ProxyEndpoint ou TargetEndpoint dos respetivos proxies de API.

Para mais informações sobre a utilização de response.payload.parse.limit ou das propriedades request.payload.parse.limit para configurar um tamanho máximo de payload de até 30 MB para fluxos de pedidos ou respostas, consulte a referência de configuração do proxy de API.

Tenha em atenção que exceder o tamanho da mensagem especificado resulta num erro protocol.http.TooBigBody.

Considere as seguintes estratégias recomendadas para processar tamanhos de mensagens grandes no Apigee:

• Recomendamos vivamente que isole os proxies de API que processam frequentemente payloads grandes num ambiente dedicado para evitar um potencial cenário de "vizinho ruidoso". Os recursos de memória e CPU do sistema são consumidos em maiores quantidades pelos proxies que gerem payloads grandes, especialmente quando usados em conjunto com políticas que interagem com payloads grandes.
• Também recomendamos que limite a utilização de políticas para interagir com payloads grandes. A utilização de políticas para analisar repetidamente os payloads de pedidos ou respostas e copiá-los pode afetar negativamente o desempenho do sistema.
• As organizações que processam grandes volumes de pedidos de payload elevado são incentivadas a fornecer endereços IP adicionais para evitar o esgotamento de portas devido ao escalonamento horizontal.
• Considere fazer streams de pedidos e respostas. Tenha em atenção que, quando faz streaming, as políticas deixam de ter acesso ao conteúdo das mensagens. Consulte Pedidos e respostas de streaming.
• Se a sua organização usar a faturação pré-paga, recomendamos que use limites configuráveis para payloads grandes apenas para proxies de API implementados no ambiente abrangente.

Processamento de falhas

• Tire partido das FaultRules para processar todo o processamento de falhas. (As políticas RaiseFault são usadas para parar o fluxo de mensagens e enviar o processamento para o fluxo FaultRules.)
• No fluxo FaultRules, use uma política AssignMessage para criar a resposta de falha, e não uma política RaiseFault. Executar condicionalmente políticas AssignMessage com base no tipo de falha que ocorre.
• Inclui sempre um controlador de falhas "catch-all" predefinido para que as falhas geradas pelo sistema possam ser mapeadas para formatos de resposta a falhas definidos pelo cliente.
• Se possível, faça sempre com que as respostas de falhas correspondam a quaisquer formatos padrão disponíveis na sua empresa ou projeto.
• Use mensagens de erro significativas e legíveis que sugiram uma solução para a condição de erro.

Consulte o artigo Processar falhas.

Persistência

Mapas de chaves-valores

• Use mapas de chave/valor apenas para conjuntos de dados limitados. Não foram concebidas para serem um armazenamento de dados a longo prazo.
• Tenha em conta o desempenho quando usar mapas de chave/valor, uma vez que estas informações são armazenadas na base de dados Cassandra.

Consulte a política de operações de mapas de valores-chave.

Colocação em cache de respostas

• Não preencha a cache de respostas se a resposta não for bem-sucedida ou se o pedido não for um GET. As criações, as atualizações e as eliminações não devem ser colocadas em cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
• Preencha a cache com um único tipo de conteúdo consistente (por exemplo, XML ou JSON). Depois de obter uma entrada responseCache, converta-a no tipo de conteúdo necessário com JSONtoXML ou XMLToJSON. Isto evita o armazenamento de dados duplicados, triplicados ou mais.
• Certifique-se de que a chave de cache é suficiente para o requisito de colocação em cache. Em muitos casos, o request.querystring pode ser usado como o identificador exclusivo.
• Não inclua a chave da API (client_id) na chave da cache, a menos que seja explicitamente necessário. Na maioria das vezes, as APIs protegidas apenas por uma chave devolvem os mesmos dados a todos os clientes para um determinado pedido. É ineficiente armazenar o mesmo valor para várias entradas com base na chave da API.
• Defina intervalos de expiração da cache adequados para evitar leituras sujas.
• Sempre que possível, tente fazer com que a política de cache de respostas que preenche a cache seja executada no PostFlow de resposta do ProxyEndpoint o mais tarde possível. Por outras palavras, deve executá-lo após os passos de tradução e mediação, incluindo a mediação baseada em JavaScript e a conversão entre JSON e XML. Ao colocar os dados mediados em cache, evita o custo de desempenho da execução do passo de mediação sempre que obtém dados em cache.

  Tenha em atenção que, em alternativa, pode querer colocar em cache dados não mediados se a mediação resultar numa resposta diferente de pedido para pedido.

• A política de cache de respostas para procurar a entrada de cache deve ocorrer no PreFlow do pedido ProxyEndpoint. Evite implementar demasiada lógica, além da geração de chaves de cache, antes de devolver uma entrada de cache. Caso contrário, as vantagens da colocação em cache são minimizadas.
• Em geral, deve sempre manter a procura na cache de respostas o mais próximo possível do pedido do cliente. Por outro lado, deve manter o preenchimento da cache de respostas o mais próximo possível da resposta do cliente.
• Quando usar várias políticas de cache de respostas diferentes num proxy, siga estas diretrizes para garantir um comportamento discreto para cada uma:
  • Executar cada política com base em condições mutuamente exclusivas. Isto ajuda a garantir que apenas uma de várias políticas de cache de respostas é executada.
  • Defina recursos de cache diferentes para cada política de cache de respostas. Especifica o recurso de cache no elemento <CacheResource> da política.

Consulte a política de ResponseCache.

Política e código personalizado

Política ou código personalizado?

• Use as políticas integradas em primeiro lugar (sempre que possível). As políticas do Apigee são reforçadas, otimizadas e suportadas. Por exemplo, use a política AssignMessage padrão e as políticas ExtractVariables em vez de JavaScript (quando possível) para criar payloads, extrair informações de payloads (XPath, JSONPath) e assim sucessivamente.
• O JavaScript é preferível ao Python e ao Java. No entanto, se o desempenho for o requisito principal, deve usar Java em vez de JavaScript.

JavaScript

• Use JavaScript se for mais intuitivo do que as políticas do Apigee (por exemplo, quando definir target.url para muitas combinações de URI diferentes).
• Análise de payloads complexos, como iterar através de um objeto JSON e codificação/descrição em Base64.
• A política de JavaScript tem um limite de tempo, pelo que os ciclos infinitos são bloqueados.
• Use sempre passos de JavaScript e coloque os ficheiros na jscpasta de recursos. O tipo de política de JavaScript pré-compila o código no momento da implementação.

Java

Aviso: para políticas JavaCallout, a confiança em bibliotecas Java incluídas no Apigee não é suportada. Essas bibliotecas destinam-se apenas à funcionalidade do produto Apigee e não existe garantia de que uma biblioteca esteja disponível de lançamento para lançamento.

• Use Java se o desempenho for a prioridade mais elevada ou se a lógica não puder ser implementada em JavaScript.
• Inclua ficheiros de origem Java no acompanhamento do código-fonte.

Consulte a Política JavaCallout para obter informações sobre a utilização de Java em proxies de API.

Python

• Não use Python, a menos que seja absolutamente necessário. Os scripts Python podem introduzir gargalos de desempenho para execuções simples, uma vez que são interpretados no tempo de execução.

Avisos de script (Java, JavaScript, Python)

• Use um try/catch global ou equivalente.
• Gerar exceções significativas e captá-las corretamente para utilização em respostas de falhas.
• Acione e detete exceções antecipadamente. Não use o try/catch global para processar todas as exceções.
• Faça verificações de nulo e indefinido, quando necessário. Um exemplo de quando o fazer é quando obtém variáveis de fluxo opcionais.
• Evite fazer pedidos HTTP/S dentro de um pedido de script. Em alternativa, use a política ServiceCallout, uma vez que esta processa as ligações de forma elegante.

JavaScript

• O JavaScript na plataforma de APIs suporta XML através de E4X.

Consulte o modelo de objeto JavaScript.

Java

Aviso: para políticas JavaCallout, a confiança em bibliotecas Java incluídas no Apigee não é suportada. Essas bibliotecas destinam-se apenas à funcionalidade do produto Apigee e não existe garantia de que uma biblioteca esteja disponível de lançamento para lançamento.

• Quando aceder a payloads de mensagens, experimente usar context.getMessage() em vez de context.getResponseMessage ou context.getRequestMessage. Isto garante que o código pode obter o payload, nos fluxos de pedido e resposta.
• Importe bibliotecas para a organização ou o ambiente do Apigee e não as inclua no ficheiro JAR. Isto reduz o tamanho do pacote e permite que outros ficheiros JAR acedam ao mesmo repositório da biblioteca.
• Importe ficheiros JAR através da API de recursos do Apigee, em vez de os incluir na pasta de recursos do proxy de API. Isto reduz os tempos de implementação e permite que os mesmos ficheiros JAR sejam referenciados por vários proxies de API. Outra vantagem é o isolamento do carregador de classes.
• Não use Java para o processamento de recursos (por exemplo, criar e gerir conjuntos de threads).

Python

• Gere exceções significativas e intercete-as corretamente para utilização em respostas de falhas do Apigee

Consulte a política de scripts Python.

ServiceCallouts

• Existem muitos exemplos de utilização válidos para usar o encadeamento de proxies, em que usa uma chamada de serviço num proxy de API para chamar outro proxy de API. Se usar o encadeamento de proxies, certifique-se de que evita chamadas recursivas de ciclos infinitos de volta ao mesmo proxy de API.

  Se estiver a estabelecer ligação entre proxies que se encontram na mesma organização e ambiente, certifique-se de que consulta o artigo sobre como encadear proxies de API para saber mais sobre a implementação de uma ligação local que evita a sobrecarga de rede desnecessária.

• Crie uma mensagem de pedido ServiceCallout com a política AssignMessage e preencha o objeto de pedido numa variável de mensagem. (Isto inclui a definição do payload, do caminho e do método do pedido.)
• O URL configurado na política requer a especificação do protocolo, o que significa que a parte do protocolo do URL, https:// por exemplo, não pode ser especificada por uma variável. Além disso, tem de usar variáveis separadas para a parte do domínio do URL e para o resto do URL. Por exemplo: https://example.com.
• Armazene o objeto de resposta de um ServiceCallout numa variável de mensagem separada. Em seguida, pode analisar a variável de mensagem e manter o payload da mensagem original intacto para utilização por outras políticas.

Consulte a política de texto de chamada de serviços.

Aceder a entidades

Política AccessEntity

• Para um melhor desempenho, procure apps por uuid em vez do nome da app.

Consulte a política AccessEntity.

Registo

• Use uma política de syslog comum em vários pacotes e no mesmo pacote. Isto mantém um formato de registo consistente.

Consulte a política de registo de mensagens.

Monitorização

Os clientes do Google Cloud não têm de verificar os componentes individuais do Apigee (routers, processadores de mensagens, etc.). A equipa de operações globais da Apigee está a monitorizar minuciosamente todos os componentes, juntamente com as verificações de funcionamento da API, tendo em conta os pedidos de verificação de funcionamento do cliente.

Apigee Analytics

O Analytics pode fornecer monitorização de API não crítica, uma vez que as percentagens de erros são medidas.

Veja os painéis de controlo do Analytics.

Depurar

A ferramenta de rastreio na IU do Apigee é útil para depurar problemas de API de tempo de execução durante o desenvolvimento ou a operação de produção de uma API.

Consulte o artigo Usar a ferramenta de depuração.

Segurança

• Use políticas de restrição de endereços IP para limitar o acesso ao seu ambiente de teste. Permita o acesso para os endereços IP das suas máquinas ou ambientes de programação e não permita o acesso a todos os outros. Consulte a política de controlo de acesso.
• Aplique sempre políticas de proteção de conteúdo (JSON e/ou XML) a proxies de API implementados em produção. Consulte a política JSONThreatProtection.
• Consulte os seguintes tópicos para ver mais práticas recomendadas de segurança:
  • Política XMLThreatProtection
  • Política RegularExpressionProtection
  • Política SOAPMessageValidation

Lógica personalizada em proxies de API

Um requisito comum ao criar proxies de API é incluir alguma lógica para processar pedidos e/ou respostas. Embora muitos requisitos possam ser cumpridos a partir de um conjunto predefinido de passos/ações/políticas, como validar um token, aplicar uma quota ou responder com um objeto em cache, muitas vezes, pode ser necessário acesso à programabilidade. Por exemplo, procurar uma localização (ponto final) numa tabela de encaminhamento com base numa chave encontrada num pedido e aplicar dinamicamente um ponto final de destino ou um método de autenticação personalizado/privado, etc.

O Apigee oferece ao programador várias opções para lidar com essa lógica personalizada. Este documento explora essas opções e quando usar cada uma delas:

Política	Exemplos de utilização de políticas
JavaScript e PythonScript	Quando usar: As políticas JavaScript e PythonScript são equivalentes em termos de capacidade. Normalmente, a familiaridade de um programador com um idioma é a motivação para escolher um em detrimento do outro. As políticas de JavaScript e PythonScript são mais adequadas para o processamento de lógica incorporada que não seja excessivamente complexa e não exija a utilização de bibliotecas de terceiros. Estas políticas não têm o mesmo desempenho que a política JavaCallout. Quando não usar: O gateway de API do Apigee não é um servidor de aplicações (nem fornece o tempo de execução de JavaScript completo, como o node.js). Se o callout demorar sempre mais de um segundo a processar, é muito provável que a lógica não pertença ao gateway e deva fazer parte do serviço subjacente. Prática recomendada: o Apigee recomenda o JavaScript em vez do PythonScript, uma vez que o JavaScript oferece melhor desempenho.
JavaCallout	Quando usar: O desempenho do processamento da lógica inline é fundamental. As bibliotecas Java existentes fornecem grande parte da lógica. Quando não usar: O gateway de API da Apigee não é um servidor de aplicações e não se destina a carregar frameworks como Spring, JEE, etc. Se o callout demorar normalmente mais de um segundo a processar, a lógica pode ser considerada funcional (lógica empresarial). Considere externalizar como um serviço. Para proteger o gateway de API Apigee contra abusos, existem restrições ao tipo de código que pode ser executado. Por exemplo, o código Java que tenta aceder a determinadas bibliotecas de criptografia ou aceder ao sistema de ficheiros é bloqueado na execução. As aplicações Java, especialmente as que dependem de bibliotecas de terceiros, podem trazer muitos (e grandes) ficheiros JAR. Estas podem tornar o tempo de arranque dos gateways mais lento.
ExternalCallout	Quando usar: Ideal para externalizar a lógica personalizada e permitir que a lógica personalizada aceda (e, se necessário, modifique) o contexto da mensagem. As invocações externas implementam o gRPC e podem ter um desempenho melhor do que uma ServiceCallout. Quando usar o Apigee ou o Apigee hybrid no Google Cloud, considere usar as Cloud Functions ou o Cloud Run para alojar essa lógica. Como uma substituição eficaz da funcionalidade Hosted Targets no Apigee Edge. Quando não usar: Para lógica simples que pode ser executada rapidamente, use a opção inline.
ServiceCallout	Quando usar: A lógica complexa é melhor implementada fora do gateway. Esta lógica pode ter o seu próprio ciclo de vida (lançamentos e controlo de versões) e não afeta o funcionamento da gateway. Quando o ponto final REST/SOAP/GraphQL já existe ou pode ser implementado facilmente Quando usar o Apigee ou o Apigee hybrid no Google Cloud, considere usar o Cloud Functions ou o Cloud Run para alojar essa lógica. Como uma substituição eficaz da funcionalidade Hosted Targets no Apigee Edge. Quando não usar: Para lógica simples que pode ser executada rapidamente, use a opção inline O proxy de API tem de transferir o contexto (como variáveis) ou receber o contexto da implementação externa

Para resumir:

1. Se a lógica for simples ou trivial, use JavaScript (de preferência) ou PythonScript.
2. Se a lógica inline exigir um desempenho melhor do que o JavaScript ou o PythonScript, use o JavaCallout.
3. Se a lógica tiver de ser externalizada, use ExternalCallout.
4. Se já tiver implementações externas e/ou os programadores estiverem familiarizados com a REST, use o ServiceCallout.

A figura seguinte ilustra este processo: