Publicar um aplicativo Jitterbit App Builder como um endpoint de API REST

Visão geral

O App Builder permite publicar os dados de um aplicativo como uma API REST, para que sistemas externos possam ler e gravar nele usando uma chave de API para autenticação, em vez de construir uma integração personalizada para cada consumidor. Esta página apresenta um exemplo completo: expor uma tabela customers de um aplicativo Northwinds como um recurso REST e, em seguida, gerar uma chave de API que um usuário específico pode usar para chamá-la.

As etapas são:

• Etapa 1: Configurar um provedor de segurança de chave de API
  Criar o provedor de segurança contra o qual os chamadores se autenticam.

• Etapa 2: Configurar um endpoint
  Atribuir ao seu aplicativo o segmento de caminho base usado em suas URLs de API REST.

• Etapa 3: Publicar um recurso
  Expor um objeto de negócio específico como um recurso do qual os chamadores podem ler e gravar, e controlar o que é retornado.

• Etapa 4: Configurar chaves de API para usuários
  Gerar a credencial que um usuário específico usa para se autenticar.

Etapa 1: Configurar um provedor de segurança de chave de API

Para proteger sua API REST, primeiro é necessário um provedor de segurança de chave de API, que o App Builder usa para validar a chave que cada chamador apresenta:

1. Selecione IDE > Security Providers.

2. Clique em + User Authentication no painel User Authentication. O diálogo Provider é aberto:

   

3. Atribua um Name ao provedor. Por exemplo: API Key.

4. Selecione API Key como o valor de Type.

5. Marque a caixa para selecionar Enabled.

6. Clique em Save.

Dependendo do seu caso de uso, é possível configurar qualquer uma das seguintes propriedades opcionais. Clique em + Property no painel Properties para abrir o diálogo Properties:

• Para permitir digitar a chave de API na barra de endereços do navegador para testes (não recomendado além de testes, pois não é muito seguro), selecione AllowApiKeyInQueryString como o Parameter e insira True como o Value, depois clique na marca de seleção para salvar o registro.

• Para permitir que a chave de API seja passada por uma conexão HTTP insegura (não recomendado), selecione AllowInsecureHttp como o Parameter e insira True para o Value, depois clique na marca de seleção para salvar o registro.

Etapa 2: Configurar um endpoint

A API REST de cada aplicativo é acessada através de um segmento de caminho base, o endpoint do aplicativo. Siga estas etapas para configurar um:

1. Selecione IDE > REST APIs.

2. Clique no botão Manage Endpoints no painel Services. O diálogo Applications é aberto:

   

3. Clique no ícone de edição do aplicativo que deseja configurar. Por exemplo: Northwinds Design.

4. Insira o valor do endpoint no campo Endpoint. Por exemplo: northwinds.

5. Clique no botão Proceed ou no ícone de marca de seleção ; ambos salvam o valor do endpoint. A linha do aplicativo agora mostra suas colunas Logging, Publish API Doc e Authentication.

6. (Desde o App Builder 4.67. Se você estiver usando uma versão anterior, pule para a Etapa 3.) Associe os provedores permitidos para autenticar as solicitações deste endpoint:

   1. Clique no ícone Authentication do aplicativo. O diálogo Authentication Providers é aberto:

1. Clique em + Autenticação. O diálogo Provedor é aberto:

   

2. Selecione um dos provedores de chave de API, HTTP ou Servidor de Autorização que você configurou. O campo Esquema é preenchido automaticamente com o esquema desse provedor, um nome único que identifica o provedor em URLs e documentos JSON. Opcionalmente, insira uma Descrição e clique em Salvar. Repita as etapas 2 e 3 para cada provedor adicional que você deseja permitir para autenticar as solicitações deste endpoint.

3. Feche o diálogo.

Etapa 3: Publicar um recurso

Com um endpoint de aplicação em vigor, agora você pode publicar um objeto de negócio específico como um recurso que sistemas externos podem chamar, controlando a quantidade de dados retornados, a versão do esquema e quais eventos são expostos. Siga estas etapas:

1. Selecione IDE > APIs REST.

2. No painel Serviços, localize a aplicação e clique no ícone de chevron em seu bloco. A página API REST dessa aplicação é aberta, exibindo suas propriedades de Serviço e Recursos em uma única visualização.

3. No painel Recursos, clique em + Recurso. O diálogo Recurso é aberto:

   

4. Defina os seguintes valores:

   • Tabela: Selecione a tabela ou objeto de negócio que este recurso expõe. Depois que o recurso é salvo, os ícones e ao lado deste campo se tornam clicáveis, levando você à página Definição de Tabela da tabela ou à página Construtor de Regras do objeto de negócio (na App Workbench), respectivamente. Apenas um dos dois está sempre disponível para um determinado recurso, dependendo se você selecionou uma tabela ou um objeto de negócio.

   • Endpoint: Insira o segmento de caminho em que a API acessa este recurso.

   • Limite Padrão GET e/ou Limite Máximo GET: Controlam a quantidade de registros retornados em chamadas GET para seu endpoint de API.

   • Compatibilidade: (Opcional, desde o App Builder 4.51.) Controla como o recurso se comporta. A compatibilidade permite que o App Builder introduza novas funcionalidades de endpoint entre versões enquanto preserva o comportamento dos endpoints existentes para compatibilidade com versões anteriores. Selecione uma das seguintes opções:

     • Versão 1: Use o comportamento REST original, no qual eventos de Inserção não são precedidos por eventos Novo. (Padrão para endpoints criados com App Builder 4.50 e anterior.)

     • Versão 2: Use um comportamento REST melhorado, no qual eventos Novo e quaisquer regras padrão são invocados antes dos eventos de Inserção. (Padrão para endpoints criados com App Builder 4.51.)

     • Versão 3: (Desde o App Builder 4.52.) Igual à versão 2, mas as APIs retornam o valor lógico em vez do valor armazenado. Por exemplo, valores booleanos são retornados como true ou false em vez de 1 ou 0. (Padrão para endpoints criados com App Builder 4.52 e posterior.)

   • Excluir da Documentação: (Opcional, desde o App Builder 4.67.) Marque para omitir este recurso do documento OpenAPI publicado da aplicação, mesmo quando a publicação de documentação está habilitada para a API REST como um todo.

   • Descrição: (Opcional.) Uma descrição do recurso, incluída no documento OpenAPI publicado da aplicação.

5. Clique em Salvar.

6. A aba Nodes do diálogo lista o nó raiz implícito deste recurso, juntamente com qualquer nó filho que você adicione. Clique no ícone de detalhes de um nó para abrir seu diálogo Node: consulte Parâmetros do nó e Campos do nó para controlar quais de seus campos são incluídos na resposta por padrão, ou Adicionar um nó filho para aninhar dados adicionais neste recurso.

7. (Desde o App Builder 4.67.) Nas propriedades Service, expanda o menu More, então clique no botão Configure Authentication. Isso abre o mesmo diálogo Authentication Providers que na Etapa 2, exibindo os provedores já associados a este endpoint e permitindo que você adicione novos se desejar:

   

   

Etapa 4: Configurar chaves de API para usuários

Por fim, gere uma chave de API vinculada a um usuário específico, para que a identidade e as permissões desse usuário se apliquem a cada solicitação feita com essa chave:

1. Selecione IDE > User Management.

2. Selecione um usuário existente ou crie um novo usuário para usar na chamada de API.

   • O usuário deve ser configurado com o Login Type Interactive.

   • O usuário não precisa ter Local Authentication.

3. No registro do usuário selecionado ou criado, clique no ícone Keys.

4. Clique em Create. O diálogo Generate Key abre:

   

5. Selecione o provedor de Chave de API que você criou na Etapa 1 como o Provider, então clique em Save. O App Builder gera um valor de chave.

   Importante

   Copie a chave gerada agora. Ela não pode ser exibida novamente quando você sair desta tela.

Para testar ou configurar o uso dos seus novos endpoints de API, use a API Key da etapa anterior, as informações de Base URL e Endpoint do documento da API, e o Name dos detalhes do recurso.