APIs REST no Jitterbit App Builder

Introdução

O App Builder oferece duas formas principais de integração com APIs REST:

• Consumir (usando configuração manual ou importando um documento OpenAPI) APIs REST externas para trazer dados para suas aplicações, ou
• Publicar os dados da sua aplicação App Builder como uma API REST para outros sistemas consumirem.

Conceitos e princípios

Aplicações como serviços web

O ambiente de design do App Builder é organizado em torno do conceito de uma aplicação. Embora as aplicações normalmente descrevam uma interface de usuário, elas possuem várias propriedades também aplicáveis a serviços web:

• As aplicações fornecem acesso a múltiplas fontes de dados.

• Grupos recebem privilégio para uma aplicação.

O App Builder estende o conceito de uma aplicação para incluir serviços web. Especificamente, os desenvolvedores têm a capacidade de definir um endpoint para uma aplicação. Por exemplo, o endpoint de uma aplicação Sales pode ser sales. O URI correspondente pode parecer assim:

https://example.com/Vinyl/rest/v1/sales

Objetos de dados como recursos

O princípio organizador do REST é o conceito de um recurso. Os recursos podem representar uma coleção de itens ou um único item. Em termos do App Builder, um objeto de dados é representado como uma coleção com linhas individuais representadas como itens nessa coleção.

Como o próprio serviço, o desenvolvedor determina o endpoint do objeto de dados. Por exemplo, o objeto de dados Customers pode ter um endpoint de customers. Nesse caso, o URI correspondente pode parecer assim:

https://example.com/Vinyl/rest/v1/sales/customers

O URI para um item específico (linha) pode parecer assim:

https://example.com/Vinyl/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

A chave primária aparece no caminho do URI.

Chaves primárias compostas podem ser especificadas separando as chaves com uma vírgula:

https://example.com/Vinyl/rest/v1/sales/customers/abc,def

Eventos como métodos HTTP

REST define um conjunto de operações correspondentes aos métodos HTTP. A API REST do App Builder suporta os seguintes métodos HTTP:

• GET /collection: Recupera os itens dentro de uma coleção. Isso mapeia para o evento Filter.

• POST /collection: Adiciona um item à coleção. Isso mapeia para o evento Insert.

• GET /collection/item: Recupera um único item da coleção. Isso mapeia para o evento Filter.

• POST /collection/item: Atualiza um item na coleção. Isso mapeia para o evento Update.

• DELETE /collection/item: Exclui um item da coleção. Isso mapeia para o evento Delete.

A API REST do App Builder não suporta atualmente os seguintes métodos HTTP:

• HEAD: O método HEAD permite que os consumidores recuperem os cabeçalhos de resposta HTTP. No momento, o App Builder não suporta essa operação.

• OPTIONS: O método OPTIONS permite que os consumidores determinem quais métodos são suportados.

• PUT (coleção ou item): O método PUT permite que os consumidores criem um item (ao endereçar a coleção) ou atualizem um item (ao endereçar o item). No entanto, como PUT é idempotente, deve incluir todos os campos. Isso limita sua utilidade em muitos cenários.

• PATCH: O método PATCH permite que os consumidores atualizem parte de um item. Isso é atualmente suportado via POST. Normalmente, PATCH usa um formato específico de patch, complicando a implementação.

Nem todos os eventos do App Builder podem ser publicados:

• New: O evento New do App Builder cria uma linha não persistente, aplicando quaisquer padrões. Os consumidores não podem invocar o evento New.

• Change: Interações com a interface do usuário invocam um pseudo-evento que executa padrões e validações sem persistir alterações. Consumidores não conseguem simular o evento Change.

• Eventos definidos pelo usuário: Além dos eventos intrínsecos, desenvolvedores podem definir seus próprios eventos. Estes não podem ser mapeados para os métodos de recurso padrão acima, mas podem ser invocados diretamente através de um padrão de URL dedicado. Para mais informações, consulte Invocar eventos personalizados abaixo.

Invocar eventos personalizados

Além dos eventos padrão mapeados para métodos HTTP acima, a API REST do App Builder pode invocar um evento personalizado definido em um objeto de negócio. Isto executa o evento de destino e quaisquer ações associadas a ele, como operações CRUD, notificações, procedimentos armazenados e regras de negócio ou validações.

Para invocar um evento personalizado, envie uma solicitação POST usando a seguinte sintaxe:

POST /{Resource}({EventName})/{RecordID}

Por exemplo, invocar um evento chamado SendWelcomeEmail em um registro de cliente usa uma URI como esta:

https://example.com/Vinyl/rest/v1/sales/customers(SendWelcomeEmail)/9ce33474-8690-4a75-ab90-65caa6c3c24e

Princípios de design RESTful

Na medida do possível, a API REST do App Builder segue estes princípios RESTful:

• Serviços são sem estado.

• Endpoints são modelados como recursos.

• Operações GET são seguras. Uma operação "segura" é aquela que não tem efeitos colaterais. Por exemplo, recuperar uma lista de clientes não altera a lista de clientes.

• Operações DELETE são inseguras, mas idempotentes. No entanto, enquanto a primeira solicitação (bem-sucedida) para deletar um item retornará um código de status 200, a segunda solicitação retornará um 404.

• Operações POST não são seguras nem idempotentes. Por isso, operações POST podem conter dados parciais.

• Códigos de status HTTP indicam se ocorreu um erro.

• Tipos de mídia são usados para realizar negociação de conteúdo. No momento, porém, o App Builder suporta apenas JSON (application/json) e UTF-8.

O App Builder não adere a todos os princípios RESTful:

• Respostas de recursos são envolvidas em um envelope. Isto permite que o App Builder inclua informações adicionais, como mensagens de eventos e resultados de validação.

• Respostas de recursos não são hipermídia: não incluem links para outros recursos.

Convenções de URI REST

No nível de coleção, o método GET suporta os seguintes recursos:

• Paginação via parâmetros $offset e $limit. O limite padrão é 10; o limite máximo é 100.

• Classificação via parâmetro $sort. O parâmetro $sort pode receber uma lista de nomes de campos delimitada por vírgula. Prefixe o nome do campo com um travessão (-) para classificar o campo em ordem decrescente. Por exemplo, a especificação de classificação $sort=-country,companyName classificaria a coleção por country, decrescente, e companyName, ascendente.

• Seleção via parâmetro $fields. O parâmetro $fields pode receber uma lista de nomes de campos delimitada por vírgula (por exemplo, $fields=customerId,country). Use um asterisco (*) para recuperar todos os campos de recurso (por exemplo, $fields=*).

• Busca por palavra-chave via parâmetro $q. O parâmetro $q recebe uma string e tenta corresponder aos valores das colunas. Qualquer linha de tabela que tenha pelo menos um valor de coluna que contenha o parâmetro $q como uma substring será retornada (por exemplo, $q=miami). A correspondência não diferencia maiúsculas de minúsculas.

• Filtragem por comparações de igualdade simples. Para limitar os resultados, especifique o nome do campo e o valor (por exemplo, countryId=USA).

• Contagem por meio do parâmetro $count. Por padrão, o App Builder não retorna uma contagem total do número de itens na coleção. Para incluir a contagem, acrescente o parâmetro count (por exemplo, $count=true).

Convenções para parâmetros:

• Parâmetros que se referem a campos de recursos não têm prefixo.

• Parâmetros que operam na coleção em si recebem o prefixo de um cifrão ($).

Validação

Um evento pode retornar um ou mais erros, avisos ou resultados de validação informacionais como parte da resposta. Cada validação incluirá um validationId, uma message (definida no IDE) e a severity da validação (erro, aviso, informação).

Para ignorar um aviso, inclua os validationIds fornecidos como o valor de um cabeçalho X-Vinyl-Ignore-Warnings em uma nova solicitação para o endpoint. Considere a resposta de exemplo abaixo:

{
  "item": {
    "contactId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
    "name": "Company Name"
  },
  "message": null,
  "validations": [
    {
      "validationId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
      "message": "32 emails will be sent, are you sure?",
      "severity": "warning"
    },
    {
      "validationId": "6bad40b7-2504-4243-9e90-100bcc7bfd13",
      "message": "No subject was provided, use default?",
      "severity": "warning"
    }
  ],
  "status": 400
}

Para ignorar o aviso que esta resposta contém, uma nova solicitação (para o mesmo endpoint e os mesmos dados) precisaria incluir as seguintes informações de cabeçalho:

X-Vinyl-Ignore-Warnings: "8d20b593-aa41-4bbb-8bee-58f17ac2bf32","6bad40b7-2504-4243-9e90-100bcc7bfd13"

Processar respostas POST

Existem duas maneiras de capturar e processar os dados retornados de uma chamada POST: vinculação com regras XP CRUD ou uso de um manipulador de sucesso.

Vinculação com regras XP CRUD

Use isso quando a chamada POST fizer parte de uma operação CRUD em que a fonte de dados é uma API externa e o destino é um banco de dados local gerenciado pelo App Builder.

• Contexto: Quando a resposta de uma chamada POST de API externa precisa ser inserida em um banco de dados local.

• Configuração:

  • Registre uma regra XP CRUD em uma ação dentro do App Builder.

  • Passe os parâmetros necessários para a chamada POST, mapeando-os para campos correspondentes em sua API externa.

• Acessando dados de resposta:

  • Após a execução bem-sucedida do POST, os dados de resposta da API ficam acessíveis em tabelas de resposta geradas automaticamente no App Builder.

  • Dentro de sua regra, você pode fazer junção com essas tabelas de resposta usando os campos id e parent_id gerados pelo sistema.

• Processamento: Use a funcionalidade XP CRUD para mapear diretamente campos dessas tabelas de resposta para colunas em seu banco de dados local para inserção ou atualização.

Usar um manipulador de sucesso

Usar um manipulador de sucesso oferece maior flexibilidade para processar respostas de API com lógica personalizada que pode não envolver mapeamento direto de banco de dados.

• Implementação:

  • Anexe um manipulador de sucesso à ação que inicia a chamada POST.

  • Recupere os dados de resposta da API dentro do manipulador de sucesso usando a função caller().

• Processamento: Implemente lógica personalizada dentro do manipulador de sucesso para analisar, manipular ou rotear os dados de resposta de acordo com os requisitos de sua aplicação.

Problemas conhecidos e limitações

• Campos binários como arquivos não são suportados no momento.

• O único tipo de conteúdo suportado é JSON (application/json).

• O único encoding de texto suportado é UTF-8.

• Coleções são limitadas a retornar 100 itens por vez.

• Chaves primárias compostas não podem conter vírgulas.

• Apenas filtragem por comparações de igualdade simples é suportada.