Conceitos-chave do Jitterbit API Manager

Esta página aborda os conceitos fundamentais que você precisa entender ao trabalhar com o Jitterbit API Manager, incluindo tipos de API, recursos de segurança aplicados através de gateways de API e estrutura de URL de serviço.

Tipos de API

Você pode criar e publicar três tipos de APIs no API Manager. Cada tipo interage com o Harmony de forma única dentro da arquitetura do sistema.

Para mais informações sobre segurança e arquitetura do sistema Jitterbit, consulte Documento técnico de segurança e arquitetura Jitterbit.

API personalizada

As APIs personalizadas expõem uma operação do Harmony para consumo. Para configurar uma API personalizada, você deve primeiro criar e implantar uma operação no Harmony. A operação pode ser qualquer operação do Studio ou Design Studio. Ao configurar a API personalizada, você faz referência à operação existente. Os consumidores de API chamam e consomem a operação através da API personalizada. As APIs personalizadas são roteadas através de agentes Jitterbit (grupos de agentes na nuvem ou agentes privados).

Como as APIs personalizadas funcionam

Quando um consumidor de API chama uma API personalizada, ocorre o seguinte processo:

1. Um consumidor de API faz uma chamada para a API personalizada no gateway de API na nuvem.
2. O gateway de API na nuvem autentica a solicitação e aplica políticas de segurança. Em seguida, roteia a solicitação de API personalizada para o serviço de mensagens, que roteia solicitações para grupos de agentes.
3. Um agente na nuvem recebe a solicitação do serviço de mensagens.
4. O agente na nuvem faz referência à operação de API personalizada que você especificou durante a configuração de API personalizada e dispara a operação implantada.
5. A operação responde com um payload de API. Este payload é consistente com o tipo de resposta que você selecionou durante a configuração de API personalizada.
6. O agente na nuvem roteia o payload de API de volta para o consumidor de API.

Para informações sobre como configurar uma API personalizada, consulte Configuração de API personalizada.

Serviço OData

Os serviços OData expõem uma operação de entidade de API do Design Studio para consumo. Para configurar um serviço OData, você deve primeiro criar e implantar uma operação de entidade de API no Harmony. Ao configurar o serviço OData, você faz referência à operação de entidade de API existente. Os consumidores de API chamam e consomem a operação através do serviço OData. Os serviços OData são roteados através de agentes Jitterbit (grupos de agentes na nuvem ou agentes privados).

Como os serviços OData funcionam

Quando um consumidor de API chama um serviço OData, ocorre o seguinte processo:

1. Um consumidor de API faz uma chamada para o serviço OData no gateway de API privado.
2. O gateway de API privado autentica a solicitação e aplica políticas de segurança. Em seguida, roteia a solicitação do serviço OData.
3. O serviço de mensagens recebe a solicitação e roteia as solicitações para grupos de agentes.
4. O agente privado recebe a solicitação do serviço de mensagens.
5. O agente privado referencia a operação de entidade do serviço OData no Harmony e dispara a operação de entidade implantada.
6. O agente privado roteia a carga útil da API da resposta da operação através do gateway de API privado de volta para o consumidor de API.

Para informações sobre como configurar um serviço OData, consulte Configuração do serviço OData.

API de proxy

As APIs de proxy funcionam com uma API de terceiros existente e não são roteadas através de agentes Jitterbit, diferentemente das APIs personalizadas ou serviços OData que expõem uma operação do Harmony para consumo. A API que você está proxying deve estar acessível ao gateway que processa a API, seja o gateway de API em nuvem ou um gateway de API privado:

• Gateway de API em nuvem: Se você usar o gateway de API hospedado pelo Jitterbit no Harmony, a API existente deve estar acessível publicamente, mesmo que protegida. A API que você está tentando fazer proxy não pode estar atrás de um firewall. Para adicionar os endereços IP do gateway de API em nuvem à lista de permissões e permitir que o gateway acesse a API que você está proxying, consulte Informações de lista de permissões e navegue até https://services.jitterbit para sua região.

• Gateway de API privado: Se você usar um gateway de API privado, a API existente deve estar acessível pelo gateway de API privado.

Como as APIs de proxy funcionam

Quando um consumidor de API chama uma API de proxy, o seguinte processo ocorre:

1. Um consumidor de API faz uma chamada para a API de proxy no gateway de API em nuvem.
2. O gateway de API em nuvem autentica a solicitação e aplica políticas de segurança. Em seguida, roteia a chamada da API de proxy e a envia para a API de terceiros que você está proxying.
3. A API de terceiros responde com uma carga útil de API que é roteada para o gateway de API em nuvem e de volta para o consumidor de API.
4. O sistema envia informações de status de tempo de execução para o banco de dados de logs de transações.

Para informações sobre como configurar uma API de proxy, consulte Configuração da API de proxy.

Segurança da API

Todas as solicitações de API no Jitterbit API Manager devem passar por gateways de API, que servem como a camada principal de aplicação de segurança para autenticação, autorização e controle de acesso. O API Manager oferece múltiplos recursos de segurança que você pode configurar e gerenciar para vários casos de uso. Para informações sobre recursos de segurança na arquitetura do sistema Jitterbit, consulte Segurança do Jitterbit.

Perfis de segurança

Por padrão, uma API é anônima e acessível publicamente quando você a cria, a menos que configure um perfil de segurança no Perfis de Segurança do API Manager e o atribua à API.

Um perfil de segurança de API governa e protege o consumo de API. Os perfis de segurança permitem que uma API publicada seja consumida apenas por um consumidor de API específico ou por um grupo de consumidores. Você pode criar e atribuir perfis de segurança se for um membro da organização com permissão de Admin.

Os administradores da organização Harmony podem exigir que você atribua perfis de segurança a cada API quando a criar usando uma configuração em políticas da organização Harmony.

Tipos de autenticação

As opções de autenticação em perfis de segurança controlam o acesso à API pelos consumidores de API. A tabela a seguir mostra os tipos de autenticação de perfil de segurança disponíveis:

Gateways de API como pontos de aplicação de segurança

Tanto o gateway de API em nuvem quanto os gateways de API privados servem como pontos de aplicação de segurança na arquitetura do API Manager. Nesses gateways, o sistema executa as seguintes ações:

• Autenticar consumidores de API usando o perfil de segurança atribuído
• Aplicar limitação de taxa e restrições de endereço IP
• Aplicar requisitos de criptografia SSL
• Registrar todo o acesso à API para auditoria de segurança
• Bloquear solicitações não autorizadas antes que elas atinjam sistemas backend

Este modelo de segurança garante proteção consistente em todos os tipos de API. Também fornece controle centralizado sobre as políticas de acesso à API.

Múltiplos perfis de segurança

É possível usar múltiplos perfis de segurança para empregar diferentes métodos de autenticação e opções de segurança no mesmo ambiente, com cada perfil direcionado a um grupo específico de consumidores de API.

Por exemplo, se você tem dois tipos de consumidores (contabilidade e finanças) e duas APIs (API-Receita e API-Orçamento) em um ambiente, e API-Receita é destinada aos consumidores de contabilidade e API-Orçamento é destinada tanto aos consumidores de contabilidade quanto de finanças, é possível criar um único perfil de segurança para consumidores de contabilidade e atribuí-lo a ambas as APIs. Você poderia então criar um perfil de segurança separado para consumidores de finanças e atribuí-lo à API-Orçamento.

O resultado dos dois perfis de segurança é que consumidores de contabilidade (usando seu perfil de segurança) podem acessar apenas a API-Receita, e consumidores de finanças (usando seu perfil de segurança separado) podem acessar tanto a API-Receita quanto a API-Orçamento.

As seguintes combinações de perfil de segurança são permitidas:

• É possível atribuir múltiplos perfis de segurança com autenticação básica a uma única API.
• É possível atribuir múltiplos perfis de segurança com autenticação por chave de API a uma única API.
• É possível atribuir uma combinação de perfis de segurança que usam autenticação básica e por chave de API a uma única API.

Qualquer outra combinação de perfil de segurança não é permitida.

Limites de taxa

Cada organização tem duas permissões, conforme indicado no contrato de licença Jitterbit da organização. Os gateways de API aplicam esses limites no ponto de entrada:

1. Permissão de chamadas de API por mês: A permissão total fornecida a uma organização em um mês. Todas as chamadas recebidas por todas as APIs (em todos os ambientes) em um único mês contam para esse limite.

2. Permissão de chamadas de API por minuto: A taxa máxima na qual a permissão de uma organização pode ser consumida.

Por padrão, um ambiente ou perfil de segurança pode acessar a permissão total de uma organização para chamadas em todas as APIs dentro de um minuto.

Depois que uma organização usa sua permissão de chamadas por mês, todas as APIs dentro da organização recebem uma resposta 429 Too Many Requests até que a permissão seja redefinida para sua permissão máxima no primeiro dia do mês seguinte.

É possível usar limites de taxa no nível de ambiente e perfil de segurança para aplicar um número máximo compartilhado de chamadas de API por minuto que podem ser feitas em todas as APIs dentro de um ambiente ao qual um perfil de segurança é atribuído.

Além dos limites acima, o gateway de API em nuvem gerenciado pela Jitterbit aplica um limite no nível de plataforma de 200 solicitações de API por minuto por organização. Solicitações que excedem esse limite são limitadas pela plataforma, que retorna uma resposta 429 Too Many Requests. Esse limite se aplica coletivamente em todos os tipos de API, incluindo APIs personalizadas, APIs de proxy e solicitações OData. Esse limite não se aplica a gateways de API privados, onde a taxa de transferência é determinada pela capacidade do servidor host.

Intervalos de IP confiáveis

Por padrão, um perfil de segurança não limita o acesso a nenhum intervalo de endereços IP predeterminado. É possível limitar o acesso às APIs dentro de um perfil de segurança a consumidores de um único endereço IP ou de um intervalo de endereços IP durante a configuração do perfil de segurança.

Quando um consumidor tenta acessar uma API com um perfil de segurança limitado a um determinado endereço IP ou intervalo, o gateway de API verifica o endereço IP do consumidor em relação aos intervalos permitidos. Endereços IP que não atendem aos critérios são rejeitados e uma mensagem Error 429 é retornada.

Modo somente SSL

É possível configurar qualquer API para usar criptografia SSL. Por padrão, todas as APIs suportam transferência tanto por HTTP quanto por HTTPS.

A opção somente SSL permite encaminhar o tráfego HTTP para garantir que toda a comunicação seja criptografada. A identidade da URL HTTPS é verificada pela Symantec Class 3 Secure Server SHA256 SSL CA. A conexão com a URL HTTPS é criptografada com criptografia moderna.

É possível ativar a opção somente SSL durante a configuração de uma API personalizada, serviço OData ou API proxy.

Logs de API

Para cada acesso a uma API, o perfil de segurança usado para acessá-la é registrado em um log. A página Logs de API exibe uma tabela com todos os logs de processamento de API e logs de depuração (se o log de depuração estiver ativado) para ajudar editores e consumidores a solucionar problemas relacionados. Os logs são exibidos para APIs personalizadas, serviços OData e APIs proxy quando são chamados através do gateway de API na nuvem ou de um gateway de API privado.

URLs de serviço de API

Acessa-se APIs personalizadas, serviços OData e APIs proxy criados através do Jitterbit API Manager usando a URL de serviço de uma API. A URL de serviço é a URL usada para consumir a API com o método de autenticação configurado.

É possível chamar a URL de serviço a partir de uma aplicação. Se a API suportar GET, pode-se colar a URL em um navegador da web para consumir a API manualmente.

Formato da URL de serviço

Todas as URLs de serviço de API seguem o mesmo formato. APIs proxy podem ter parâmetros de caminho de serviço adicionais:

<Protocol>://<Base URL>/<Environment URL Prefix>/<Version>/<Service Root>

<Protocol>://<Base URL>/<Environment URL Prefix>/<Version>/<Service Root>/<Service Path>

Componentes da URL de serviço

A URL de serviço de cada API é construída automaticamente com estas partes:

Solução de problemas

Para solução de problemas relacionada, consulte o seguinte no guia de solução de problemas do API Manager:

• Erro 429: Limite mensal de chamadas de API excedido

• Limite de taxa no nível da plataforma: 200 solicitações por minuto

• HTTP 504 Gateway Timeout