Conceitos-chave para o 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 por meio de gateways de API e a estrutura da URL do 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 maneira única dentro da arquitetura do sistema.

Para mais informações sobre segurança e arquitetura do Jitterbit, consulte o documento técnico sobre segurança e arquitetura do Jitterbit.

API Personalizada

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 Integration Studio ou do Design Studio. Ao configurar a API personalizada, você faz referência à operação existente. Os consumidores da API chamam e consomem a operação por meio da API personalizada. APIs personalizadas são roteadas através de agentes Jitterbit (sejam grupos de agentes em nuvem ou agentes privados).

Como as APIs personalizadas funcionam

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

1. Um consumidor de API faz uma chamada para a API personalizada 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, ele roteia a solicitação da API personalizada para o serviço de mensagens, que roteia solicitações para grupos de agentes.
3. Um agente em nuvem recebe a solicitação do serviço de mensagens.
4. O agente em nuvem faz referência à operação da API personalizada que você especificou durante a configuração da API personalizada e aciona a operação implantada.
5. A operação responde com uma carga útil da API. Essa carga útil é consistente com o tipo de resposta que você selecionou durante a configuração da API personalizada.
6. O agente em nuvem roteia a carga útil da API de volta para o consumidor da API.

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

Serviço OData

Os serviços OData expõem uma operação de entidade API do Design Studio para consumo. Para configurar um serviço OData, você deve primeiro criar e implantar uma operação de entidade API no Harmony. Ao configurar o serviço OData, você faz referência à operação de entidade API existente. Os consumidores da 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 (sejam grupos de agentes em nuvem ou agentes privados).

Como os serviços OData funcionam

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

1. Um consumidor da API faz uma chamada para o serviço OData no gateway API privado.
2. O gateway 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 faz referência à operação de entidade API do serviço OData no Harmony e aciona a operação de entidade implantada.
6. O agente privado roteia o payload da API da resposta da operação através do gateway API privado de volta para o consumidor da API.

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

Proxy API

APIs proxy trabalham com uma API de terceiros existente e não roteiam através dos agentes Jitterbit, ao contrário das APIs personalizadas ou serviços OData que expõem uma operação Harmony para consumo. A API que você está proxyando deve ser 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 que a Jitterbit hospeda no Harmony, a API existente deve ser publicamente acessível, mesmo que esteja segura. A API que você está tentando proxyar não pode estar atrás de um firewall. Para permitir os endereços IP do gateway de API em nuvem e permitir o acesso do gateway à API que você está proxyando, veja informações sobre a 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 em nuvem.
2. O gateway de API em nuvem autentica a solicitação e aplica políticas de segurança. Em seguida, ele roteia a chamada da API proxy e a envia para a API de terceiros que você está proxyando.
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 em tempo de execução para o banco de dados de logs de transação.

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

Segurança da API

Todas as solicitações de API no Jitterbit API Manager devem passar pelos gateways de API, que servem como a principal camada de aplicação de segurança para autenticação, autorização e controle de acesso. O API Manager fornece vários recursos de segurança que você pode configurar e gerenciar para diferentes casos de uso. Para informações sobre recursos de segurança dentro da arquitetura do sistema Jitterbit, veja 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 você configure um perfil de segurança na página 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. Perfis de segurança permitem que uma API publicada seja consumida apenas por um consumidor de API específico ou 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 ao criá-la, 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 em nuvem quanto os gateways de API privados atuam como pontos de aplicação de segurança na arquitetura do Gerenciador de API. Nestes gateways, o sistema realiza as seguintes ações:

• Autenticar consumidores de API usando o perfil de segurança atribuído
• Aplicar limites 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 cheguem aos sistemas de backend

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

Múltiplos perfis de segurança

Você pode 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 (contabilidade e finanças), e duas APIs (API-Renda e API-Orçamento) em um ambiente, e API-Renda for destinada a consumidores de contabilidade e API-Orçamento for destinada tanto a consumidores de contabilidade quanto de finanças, você pode 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 a API-Orçamento.

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

Essas combinações de perfis de segurança são permitidas:

• Você pode atribuir múltiplos perfis de segurança com autenticação básica a uma única API.
• Você pode atribuir múltiplos perfis de segurança com autenticação por chave de API a uma única API.
• Você pode atribuir uma combinação de perfis de segurança que utilizam autenticação básica e autenticação 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 possui duas permissões, conforme declarado no contrato de licença da 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 chamadas de uma organização em todas as APIs dentro de um minuto.

Depois que uma organização utiliza sua permissão de chamadas por mês, todas as APIs dentro da organização recebem um Error 429 até que a permissão seja redefinida para seu limite máximo no primeiro dia do mês seguinte.

Você pode usar limites de taxa no nível de ambiente e perfil de segurança para impor 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 está atribuído.

Faixas de IP confiáveis

Por padrão, um perfil de segurança não limita o acesso a nenhuma faixa de endereços IP predeterminada. Você pode limitar o acesso às APIs dentro de um perfil de segurança a consumidores de um único endereço IP ou uma faixa 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 que está limitado a um certo endereço IP ou faixa, o gateway de API verifica o endereço IP do consumidor em relação às faixas permitidas. Endereços IP que não atendem aos critérios são rejeitados e uma mensagem de Error 429 é retornada.

Modo somente SSL

Você pode configurar qualquer API para usar criptografia SSL. Por padrão, toda API suporta transferências tanto em HTTP quanto em HTTPS.

A opção somente SSL permite que você encaminhe 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.

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

Logs da 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 da API exibe uma tabela de todos os logs de processamento da API e logs de depuração (se o registro 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 proxy quando são chamados através do gateway de API em nuvem ou de um gateway de API privado.

URLs de serviço da API

Você acessa APIs personalizadas, serviços OData e APIs proxy que são criadas através do Jitterbit API Manager usando a URL de serviço da 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 suportar GET, você pode 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 da API seguem o mesmo formato. APIs proxy podem ter parâmetros de caminho de serviço adicionais:

<Protocolo>://<URL Base>/<Prefixo da URL do Ambiente>/<Versão>/<Raiz do Serviço>

<Protocolo>://<URL Base>/<Prefixo da URL do Ambiente>/<Versão>/<Raiz do Serviço>/<Caminho do Serviço>

Componentes da URL do Serviço

A URL de serviço de cada API é construída automaticamente a partir dessas partes: