Práticas recomendadas para projeto e desenvolvimento de proxy de API

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O objetivo deste documento é fornecer um conjunto de padrões e práticas recomendadas para desenvolvimento com o Apigee Edge. Os tópicos abordados aqui incluem design, codificação, uso de políticas, monitoramento e depuração. As informações foram coletadas pela experiência dos desenvolvedores que trabalham com a Apigee para implementar programas de API bem-sucedidos. Este é um documento dinâmico e será atualizado periodicamente.

Além das diretrizes aqui, confira a postagem da comunidade Apigee Edge Antipatterns.

Padrões de desenvolvimento

Comentários e documentação

  • Forneça comentários in-line nas configurações ProxyEndpoint e TargetEndpoint. Os comentários aumentam a legibilidade de um fluxo, especialmente quando os nomes de arquivo da política não são descritivos o suficiente para expressar a funcionalidade subjacente.
  • Faça comentários úteis. Evite comentários óbvios.
  • Use recuo consistente, espaçamento, alinhamento vertical etc.

Codificação em estilo de framework

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

  • Para ativar a DRY ("não se repita", na sigla em inglês), quando possível, as configurações e os scripts de política precisam implementar funções especializadas e reutilizáveis. Por exemplo, uma política dedicada para extrair parâmetros de consulta de mensagens de solicitação pode ser chamada de ExtractVariables.ExtractRequestParameters. Uma política dedicada para injetar cabeçalhos CORS pode ser chamada de AssignMessage.SetCORSHeaders. Essas políticas podem ser armazenadas no sistema de controle de origem e adicionadas a cada proxy de API que precisa extrair parâmetros ou definir cabeçalhos CORS, sem a necessidade de criar configurações redundantes e, portanto, menos gerenciáveis.
  • Limpe políticas e recursos não utilizados (JavaScript, Java, XSLT etc.) de proxies de API, especialmente recursos grandes que podem atrasar a importação e a implantação de procedimentos.

Convenções de nomenclatura

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

Desenvolvimento de proxy de API

Considerações iniciais sobre design

  • Para ver orientações sobre o design da API RESTful, faça o download do e-book Design da API da Web: o link ausente.
  • Aproveite as políticas e funcionalidades do Apigee Edge sempre que possível para criar proxies de API. Evite codificar toda a lógica de proxy nos recursos JavaScript, Java ou Python.
  • Crie fluxos de maneira organizada. Vários fluxos, cada um com uma única condição, são preferidos para vários anexos condicionais no mesmo Preflow e no Postflow.
  • Como "failsafe", crie um proxy de API padrão com um ProxyEndpoint BasePath de /. Ele pode ser usado para redirecionar solicitações básicas da API para um site de desenvolvedor, para retornar uma resposta personalizada ou executar outra ação mais útil do que retornar o messaging.adaptors.http.flow.ApplicationNotFound padrão.
  • Use os recursos do TargetServer para desacoplar as configurações de TargetEndpoint dos URLs concretos, oferecendo suporte à promoção em vários ambientes.
    Consulte Balanceamento de carga entre servidores de back-end.
  • Se você tiver várias RouteRules, crie uma como "padrão", ou seja, como uma RouteRule sem condição. Certifique-se de que a RouteRule padrão esteja definida por último na lista de rotas condicionais. As RouteRules são avaliadas de cima para baixo no ProxyEndpoint.
    Consulte Referência de configuração do proxy da API.
  • Tamanho do pacote do proxy de API: os pacotes de proxy de API não podem ser maiores que 15 MB. No Apigee Edge para Private Cloud, é possível mudar a limitação de tamanho modificando a propriedade thrift_framed_transport_size_in_mb nos seguintes locais: cassandra.yaml (no Cassandra) e conf/apigee/management-server/repository.properties.
  • Controle de versão da API: para conferir as ideias e recomendações da Apigee sobre o controle de versão da API, consulte a seção "Controle de versão" no e-book Design da API da Web: o link ausente.

Como ativar o CORS

Antes de publicar suas APIs, você precisará ativar o CORS nos proxies de API para oferecer suporte a solicitações de origem cruzada do cliente.

O compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que chamadas JavaScript XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de domínios que não são de origem. O CORS é uma solução comumente implementada na política de mesma origem que é aplicada por todos os navegadores. Por exemplo, se você fizer uma chamada XHR para a API Twitter a partir do código JavaScript em execução no seu navegador, a chamada falhará. Isso ocorre porque o domínio que veicula a página para o navegador não é o mesmo que usa a API Twitter. O CORS oferece uma solução para esse problema permitindo que os servidores optem por permitir o compartilhamento de recursos entre origens.

Para informações sobre como ativar o CORS nos proxies da API antes de publicar as APIs, consulte Como adicionar suporte ao CORS a um proxy de API.

Tamanho do payload da mensagem

Para evitar problemas de memória no Edge, o tamanho do payload da mensagem é restrito a 10 MB. Exceder esses tamanhos resulta em um erro protocol.http.TooBigBody.

Esse problema também é discutido nesta postagem na Comunidade da Apigee.

Confira a seguir as estratégias recomendadas para lidar com mensagens grandes no Edge:

  • Solicitações de stream e respostas. Observe que, ao fazer streaming, as políticas não têm mais acesso ao conteúdo da mensagem. Consulte Solicitações e respostas de streaming.
  • No Edge for Private Cloud versão 4.15.07 e anteriores, edite o arquivo http.properties do processador de mensagens para aumentar o limite no parâmetro HTTPResponse.body.buffer.limit. Faça testes antes de implantar a mudança na produção.
  • No Edge para nuvem privada versão 4.16.01 e mais recentes, as solicitações com um payload precisam incluir o cabeçalho Content-Length ou, no caso de streaming, o cabeçalho "Transfer-Encoding: chunked". Para um POST em um proxy de API com um payload vazio, é necessário transmitir um Content-Length de 0.
  • No Edge for Private Cloud versão 4.16.01 e mais recentes, defina as seguintes propriedades em /opt/apigee/router.properties ou message-processor.properties para mudar os limites. Consulte Definir o limite de tamanho da mensagem no roteador ou processador de mensagens para saber mais.

    Ambas as propriedades têm um valor padrão de "10m", correspondente a 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Gerenciamento de falhas

  • Aproveite as FaultRules para processar todo o tratamento de falhas. As políticas RaiseFault são usadas para interromper o fluxo de mensagens e enviar o processamento para o Fluxo FaultRules.
  • Dentro do Fluxo FaultRules, use as políticas AssignMessages para criar a resposta de falha, não as políticas RaiseFault. Execute de modo condicional as políticas AssignMessage com base no tipo de falha que ocorre.
  • Sempre inclui um gerenciador de falhas padrão "pega-tudo" para que as falhas geradas pelo sistema sejam mapeadas para formatos de resposta a falhas definidos pelo cliente.
  • Se possível, sempre faça com que as respostas de falha correspondam a todos os 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 do erro.

Consulte Como lidar com falhas.

Para ver as práticas recomendadas do setor, consulte Design de resposta de erro RESTful.

Persistência

Mapas de chave-valor

  • Use mapas de chave-valor apenas para conjuntos de dados limitados. Eles não são projetados para ser um armazenamento de dados de longo prazo.
  • Pense no desempenho ao usar mapas de chave-valor, já que essas informações são armazenadas no banco de dados do Cassandra.

Consulte a política de operações de mapeamento de chave-valor.

Armazenamento de respostas em cache

  • Não preencha o cache de resposta se a resposta não tiver êxito ou se a solicitação não for GET. Criações, atualizações e exclusões não devem ser armazenadas em cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Preencha o cache com um único tipo de conteúdo consistente (por exemplo, XML ou JSON). Depois de recuperar uma entrada de responseCache, converta para o tipo de conteúdo necessário com JSONtoXML ou XMLToJSON. Isso impedirá o armazenamento duplo, triplo ou mais dados.
  • Verifique se a chave de cache é suficiente para o requisito de armazenamento em cache. Em muitos casos, o request.querystring pode ser usado como o identificador exclusivo.
  • Não inclua a chave de API (client_id) na chave de cache, a menos que seja explicitamente necessário. Na maioria das vezes, as APIs protegidas apenas por uma chave retornam os mesmos dados para todos os clientes de uma determinada solicitação. Não é eficiente armazenar o mesmo valor para várias entradas com base na chave de API.
  • Defina intervalos de expiração de cache apropriados para evitar leituras sujas.
  • Sempre que possível, tente fazer com que a política de cache de resposta que preencha o cache seja executada no PostFlow da resposta do ProxyEndpoint o mais tarde possível. Em outras palavras, faça-o depois das etapas de tradução e mediação, incluindo mediação baseada em JavaScript e conversão entre JSON e XML. Ao armazenar dados de mediação em cache, você evita o custo de desempenho da execução da etapa de mediação toda vez que recupera dados em cache.

    Em vez disso, convém armazenar os dados não mediados em cache se a mediação resultar em uma resposta diferente da solicitação para a solicitação.

  • A política de cache de resposta para pesquisar a entrada do cache precisa ocorrer no PreFlow da solicitação ProxyEndpoint. Evite implementar uma lógica muito diferente, além da geração de chaves de cache, antes de retornar uma entrada de cache. Caso contrário, os benefícios do armazenamento em cache são minimizados.
  • Em geral, você precisa sempre manter a pesquisa em cache da resposta o mais próxima possível da solicitação do cliente. Por outro lado, mantenha o preenchimento de cache de resposta o mais próximo possível da resposta do cliente.
  • Ao usar várias políticas de cache de resposta diferentes em um proxy, siga estas diretrizes para garantir um comportamento distinto para cada:
    • Execute cada política com base em condições mutuamente exclusivas. Isso ajudará a garantir que apenas uma das várias políticas de cache de resposta seja executada.
    • Defina recursos de cache diferentes para cada política de cache de resposta. O recurso de cache é especificado no elemento <CacheResource> da política.

Consulte Política de cache de resposta.

Política e código personalizado

Política ou código personalizado?

  • Use políticas incorporadas em primeiro lugar (quando possível). As políticas da Apigee são reforçadas, otimizadas e compatíveis. Por exemplo, use as políticas AssignMessage e ExtractVariables padrão em vez de JavaScript (quando possível) para criar payloads, extrair informações de payloads (XPath, JSONPath) etc.
  • O JavaScript tem preferência sobre Python e Java. No entanto, se o desempenho for o principal requisito, o Java deverá ser usado em JavaScript.

JavaScript

  • Use JavaScript se for mais intuitivo do que políticas da Apigee (por exemplo, ao definir target.url para muitas combinações de URI diferentes).
  • Análise de payload complexa, como iteração por meio de um objeto JSON e codificação/decodificação Base64.
  • A política JavaScript tem um limite de tempo, portanto, loops infinitos são bloqueados.
  • Sempre use as etapas de JavaScript e coloque os arquivos na pasta de recursos jsc. O tipo de política JavaScript pré-compila o código no momento da implantação.

Consulte Como programar proxies de API com o JavaScript.

Java

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

Consulte Converter a resposta em letras maiúsculas com uma chamada Java e Política de chamada Java para informações sobre como usar Java em proxies de API.

Python

  • Não use Python, a menos que seja absolutamente necessário. Scripts Python podem introduzir gargalos de desempenho para execuções simples, tendo em vista que são interpretados no ambiente de execução.

Frases de destaque de script (Java, JavaScript, Python)

  • Use um try/catch global ou equivalente.
  • Crie exceções significativas e capture-as adequadamente para uso em respostas de falha.
  • Acione e capture exceções antecipadamente. Não use o try/catch global para processar todas as exceções.
  • Execute verificações nulas e indefinidas, quando necessário. Um exemplo de quando fazer isso é ao recuperar variáveis de fluxo opcionais.
  • Evite fazer solicitações HTTP/S dentro de uma chamada de script. Em vez disso, use a política ServiceCallout da Apigee, tendo em vista que a política processa conexões normalmente.

JavaScript

  • O JavaScript na plataforma de API é compatível com XML via E4X.

Consulte Modelo de objeto JavaScript.

Java

  • Ao acessar os payloads das mensagens, tente usar context.getMessage() vs. context.getResponseMessage ou context.getRequestMessage. Isso garante que o código possa recuperar o payload em fluxos de solicitação e resposta.
  • Importe bibliotecas para a organização ou o ambiente do Apigee Edge e não as inclua no arquivo JAR. Isso reduz o tamanho do pacote e permite que outros arquivos JAR acessem o mesmo repositório da biblioteca.
  • Importe arquivos JAR usando a API de recursos da Apigee em vez de incluí-los na pasta de recursos de proxy da API. Isso reduzirá os tempos de implantação e permitirá que os mesmos arquivos JAR sejam referenciados por vários proxies de API. Outro benefício é o isolamento do carregador de classes.
  • Não use Java para processamento de recursos (por exemplo, criar e gerenciar pools de linhas de execução).

Consulte Converter a resposta em maiúsculas com uma chamada Java.

Python

  • Crie exceções significativas e capture-as adequadamente para uso em respostas de falha da Apigee.

Veja a política do script Python.

ServiceCallouts

  • Há muitos casos de uso válidos para o uso do encadeamento de proxies, em que você usa uma chamada de serviço em um proxy de API para chamar outro proxy de API. Se você usar o encadeamento de proxy, evite as chamadas recursivas de "loop infinito" sobre o mesmo proxy da API.

    Se você estiver se conectando entre proxies que estão na mesma organização e ambiente, verifique se há Encadeamento de proxies de API juntos para saber mais sobre como implementar uma conexão local que evita sobrecarga desnecessária de rede.

  • Crie uma mensagem de solicitação ServiceCallout usando a política AssignMessage e preencha o objeto de solicitação em uma variável de mensagem. Isso inclui definir o payload da solicitação, o caminho e o método.
  • O URL configurado na política requer a especificação do protocolo, ou seja, a parte do protocolo do URL, https://, por exemplo, não pode ser especificada por uma variável. Além disso, use variáveis separadas para a parte do domínio do URL e para o restante do URL. Por exemplo: https://{domain}/{path}
  • Armazene o objeto de resposta para um ServiceCallout em uma variável de mensagem separada. Em seguida, é possível analisar a variável da mensagem e manter o payload da mensagem original intacto para uso por outras políticas.

Consulte Política de chamadas de serviço.

Como acessar entidades

Política AccessEntity

  • Para melhorar o desempenho, procure aplicativos por uuid em vez do nome do aplicativo.

Consulte a Política de acesso à entidade.

Logging

  • Use uma política syslog comum em todos os pacotes e dentro do mesmo pacote. Isso manterá um formato de geração de registros consistente.

Consulte a política MessageLogging.

Monitoramento

Os clientes do Cloud não precisam verificar componentes individuais do Apigee Edge (Roteadores, processadores de mensagem etc.). A equipe de operações globais da Apigee está monitorando de forma completa todos os componentes com verificações de integridade da API, de acordo com as solicitações de verificação de integridade do cliente.

Análise da Apigee

As análises podem fornecer monitoramento não crítico da API à medida que as porcentagens de erro são medidas.

Consulte os painéis do Google Analytics.

Trace

A ferramenta Trace na interface de gerenciamento de APIs do Edge é útil para depurar problemas da API de ambiente de execução durante a operação de desenvolvimento ou produção de uma API.

Consulte Como usar a ferramenta Trace.

Segurança