API REST no Jitterbit App Builder

Introdução

REST é um estilo arquitetônico de serviço web. REST define um conjunto de operações sem estado que podem ser realizadas em recursos. O App Builder permite que os desenvolvedores publiquem objetos de dados como recursos REST. Os consumidores podem realizar operações nesses recursos, que se traduzem em invocações de eventos de objetos de dados.

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 que também se aplicam a serviços web:

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

• Grupos recebem privilégios 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 para a aplicação de Vendas pode ser vendas. O URI correspondente pode ser assim:

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

Objetos de dados como recursos

O princípio organizador do REST é o conceito de "recurso". 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.

Assim como o serviço em si, o desenvolvedor determina o endpoint do objeto de dados. Por exemplo, o objeto de dados Clientes pode ter um endpoint de clientes. Nesse caso, o URI correspondente pode ser assim:

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

O URI para um item específico (linha) pode ser 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 corresponde ao evento Filter.

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

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

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

• DELETE /collection/item: Exclui um item da coleção. Isso corresponde ao evento DELETE.

A API REST do App Builder atualmente não suporta 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 se referir à coleção) ou atualizem um item (ao se referir ao item). No entanto, como o PUT é idempotente, ele 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 um POST. Normalmente, o PATCH utiliza um formato específico de patch, complicando a implementação.

Nem todos os eventos do App Builder podem ser publicados:

• Novo: 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.

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

• Eventos definidos pelo usuário: Além dos eventos intrínsecos, os desenvolvedores podem definir seus próprios eventos. Atualmente, esses não podem ser mapeados para métodos de recurso.

Princípios de design RESTful

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

• Os serviços são sem estado.

• Os endpoints são modelados como recursos.

• As 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.

• As 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.

• As operações POST não são seguras nem idempotentes. Por causa disso, as operações POST podem conter dados parciais.

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

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

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

• As respostas de recursos são envolvidas em um envelope. Isso permite que o App Builder inclua informações adicionais, como mensagens de evento e resultados de validação.

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

Convenções de URI REST

No nível da 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.

• Ordenação via um parâmetro $sort. O parâmetro $sort pode aceitar uma lista de nomes de campos delimitada por vírgulas. Prefixe o nome do campo com um traço (-) para ordenar o campo em ordem decrescente. Por exemplo, a especificação de ordenação $sort=-country,companyName ordenaria a coleção por país, em ordem decrescente, e companyName, em ordem crescente.

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

• Pesquisa por palavra-chave via um parâmetro $q. O parâmetro $q aceita uma string e tenta corresponder aos valores das colunas. Qualquer linha da tabela que tenha pelo menos um valor de coluna que contenha o parâmetro $q como uma sub-string será retornada (por exemplo, $q=miami). Observe que a correspondência é insensível a maiúsculas e minúsculas.

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

• Contagem via o parâmetro $count. Por padrão, o App Builder não retornará uma contagem total do número de itens dentro da coleção. Para incluir a contagem, anexe o parâmetro de contagem (por exemplo, $count=true).

Convenções para parâmetros:

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

• Parâmetros que operam na própria coleção são prefixados com um sinal de dólar ($).

Validação

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

Se você deseja 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.

Por exemplo, para a seguinte resposta:

{
  "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
}

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"

Manipulando respostas POST

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

Vinculação com regras XP CRUD

Use isso quando a chamada POST fizer parte de uma operação CRUD onde 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 uma 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 os 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 tornam-se acessíveis dentro de tabelas de resposta geradas automaticamente no App Builder.

  • Dentro da sua regra, você pode se juntar a essas tabelas de resposta usando os campos id e parent_id gerados pelo sistema.

• Processamento: Use a funcionalidade XP CRUD para mapear diretamente os 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 da API com lógica personalizada que pode não envolver mapeamento direto para o 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 direcionar os dados de resposta de acordo com os requisitos da sua aplicação.

Problemas conhecidos e limitações

• Campos binários, como arquivos, não são suportados atualmente.

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

• A única codificação de texto suportada é UTF-8.

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

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

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