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 implementados por meio 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 de forma única com o Harmony dentro da arquitetura do sistema.

Para mais informações sobre segurança e arquitetura do sistema Jitterbit, consulte Jitterbit security and architecture white paper.

Custom API

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

Como as custom APIs funcionam

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

1. Um consumidor de API faz uma chamada para a custom API no gateway de API de nuvem.
2. O gateway de API de nuvem autentica a solicitação e implementa políticas de segurança. Em seguida, roteia a solicitação da custom API para o serviço de mensagens, que roteia solicitações para grupos de agentes.
3. Um agente de nuvem recebe a solicitação do serviço de mensagens.
4. O agente de nuvem faz referência à operação da custom API que você especificou durante a configuração de custom API 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 custom API.
6. O agente de nuvem roteia o payload de API de volta para o consumidor de API.

Para informações sobre como configurar uma custom API, consulte Custom API configuration.

OData service

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

Como os OData services funcionam

Quando um consumidor de API chama um OData service, 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 obter informações sobre como configurar um serviço OData, consulte Configuração do serviço OData.

API Proxy

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

• Gateway de API na nuvem: Se você usar o gateway de API hospedado pelo Jitterbit no Harmony, a API existente deve ser acessível publicamente, mesmo se 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 na nuvem à lista de permissões e permitir que o gateway acesse a API que você está fazendo proxy, 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 ser acessível pelo gateway de API privado.

Como as APIs proxy funcionam

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

1. Um consumidor de API faz uma chamada para a API proxy 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 chamada da API 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 na 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 obter informações sobre como configurar uma API proxy, consulte Configuração da API proxy.

Segurança de API

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

Perfis de segurança

Por padrão, uma API é anônima e publicamente acessível 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 da 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 cria usando uma configuração nas políticas da organização Harmony.

Tipos de autenticação

As opções de autenticação nos 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 na nuvem quanto os gateways de API privados funcionam como pontos de aplicação de segurança na arquitetura do API Manager. Nesses gateways, o sistema realiza as seguintes ações:

• Autentica consumidores de API usando o perfil de segurança atribuído
• Aplica limitação de taxa e restrições de endereço IP
• Impõe requisitos de criptografia SSL
• Registra todo o acesso à API para auditoria de segurança
• Bloqueia solicitações não autorizadas antes de chegarem aos sistemas backend

Este modelo de segurança garante proteção consistente em todos os tipos de API. Também oferece controle centralizado sobre 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ê tiver dois tipos de consumidores (accounting e finance) e duas APIs (API-Revenue e API-Budget) em um ambiente, e API-Revenue for destinada a consumidores accounting e API-Budget for destinada aos consumidores accounting e finance, é possível criar um único perfil de segurança para consumidores accounting e atribuí-lo a ambas as APIs. Você poderia então criar um perfil de segurança separado para consumidores finance e atribuí-lo a API-Budget.

O resultado dos dois perfis de segurança é que consumidores accounting (usando seu perfil de segurança) só conseguem acessar API-Revenue, e consumidores finance (usando seu perfil de segurança separado) conseguem acessar tanto API-Revenue quanto API-Budget.

Estas 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 de 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 de 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 declarado no contrato de licença Jitterbit da organização. Os gateways de API aplicam esses limites no ponto de entrada:

1. Permissão de requisições 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 requisições 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 da organização para requisições em todas as APIs dentro de um minuto.

Depois que uma organização usa sua permissão de requisições por mês, todas as APIs na 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 do ambiente e do perfil de segurança para impor um número máximo compartilhado de requisições de API por minuto que podem ser feitas em todas as APIs em um ambiente ao qual um perfil de segurança é atribuído.

Além dos limites acima, o gateway de API na nuvem gerenciado pelo Jitterbit aplica um limite de nível de plataforma de 200 requisições de API por minuto por organização. Solicitações que excedem esse limite sofrem limitação de taxa pela plataforma, que retorna uma resposta 429 Too Many Requests. Este limite se aplica coletivamente em todos os tipos de API, incluindo APIs customizadas, APIs proxy e solicitações OData. Este limite não se aplica aos 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 predeterminado de endereços IP. É 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

Você pode configurar qualquer API para usar criptografia SSL. Por padrão, todas as APIs suportam transferência HTTP e HTTPS.

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

Você pode ativar a opção somente SSL durante a configuração de uma API personalizada, serviço OData ou API de proxy.

Logs de API

Para cada acesso a uma API, o perfil de segurança usado para acessar a API é 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 habilitado) para ajudar editores e consumidores a solucionar problemas relacionados. Os logs são exibidos para APIs personalizadas, serviços OData e APIs de proxy quando são chamados através do gateway de API em nuvem ou de um gateway de API privado.

URLs de serviço de API

Você acessa APIs personalizadas, serviços OData e APIs de proxy criadas 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 usando o método de autenticação configurado.

Você pode chamar a URL de serviço a partir de um aplicativo. Se a API suporta GET, você pode colar a URL em um navegador da web para consumir a API manualmente.

Formato de URL de serviço

Todas as URLs de serviço de API seguem o mesmo formato. APIs de 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 é automaticamente construída com estas partes:

Solução de problemas

Para consultar a solução de problemas relacionada, veja 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 requisições por minuto

• HTTP 504 Gateway Timeout