Recomendações da API REST no Jitterbit App Builder

Introdução

Esta página oferece orientações para desenvolvedores que buscam implementar uma API REST compatível com o App Builder. Assume-se que o desenvolvedor está focado em criar um serviço REST CRUD. Muitos dos princípios utilizados em uma API CRUD serão aplicáveis a outras APIs. No entanto, uma API CRUD provavelmente terá os requisitos mais abrangentes que interagem com o App Builder (paginação, pesquisa, filtragem etc).

Envelope

Os corpos de solicitação e resposta da API REST do App Builder são encapsulados em um envelope. Os envelopes permitem que os dados sejam enviados para e recebidos de um endpoint da API fora da carga útil do endpoint.

Envelope do corpo da solicitação

O corpo da solicitação da API REST do App Builder contém estas propriedades do envelope:

Exemplo JSON

{
  "item": {}
}

Envelope do corpo da resposta

O corpo da resposta da API REST do App Builder contém estas propriedades do envelope:

Exemplo JSON

{
  "message": "",
  "status": 200,
  "validations": [],
  "items": []
}

Validações

Quando erros são encontrados, um objeto de validação é adicionado ao array de validações no envelope de resposta. O objeto de validação possui as seguintes propriedades:

Exemplo JSON

{
  "message": "",
  "status": 400,
  "validations": [
    {
      "message": "CustomerId is mandatory.",
      "severity": "error",
      "field": "customerId"
    },
    {
      "message": "CompanyName is mandatory.",
      "severity": "error",
      "field": "companyName"
    }
  ],
}

Operações principais

Estas são as operações básicas que seu serviço REST deve suportar. Alguns serviços, é claro, optarão por não implementar certos métodos (por exemplo, um serviço somente leitura implementaria apenas os métodos Obter Único/Obter Muitos).

Obter único

A operação Obter Único retorna um único registro. O identificador do registro é especificado na URL.

Método HTTP

GET

Exemplo de URL

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

Exemplo JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Obter muitos

A operação Obter Muitos retorna muitos registros de uma coleção. Muitas vezes, essa operação é usada juntamente com paginação, para permitir que uma coleção de registros seja explorada.

Se possível, deve ser retornada uma contagem dos registros na coleção. Isso permite que o App Builder exiba a contagem de registros na interface do usuário, além de informar à interface quando o final da coleção foi alcançado.

Método HTTP

GET

Exemplo de URL

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

Exemplo JSON

{
  "count": 2,
  "items": [
    {
      "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
      "name": "John Henry",
      "address": "130 Plutonium Drive"
    },
    {
      "customerId": "9775de33-08fc-4cd2-98ef-d91f3d5355b1",
      "name": "Sally Keith",
      "address": "4500 Neutrino Road"
    }
  ],
  // envelope properties
}

Criar

A operação Criar irá criar um novo registro. O identificador do registro existe dentro do corpo JSON.

Observe que o registro inteiro é retornado na resposta. Isso é útil em casos onde alguns campos são criados ou atualizados pelo servidor (como um carimbo de data/hora de criação do registro).

Método HTTP

POST

Exemplo de URL

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

Exemplo de corpo da requisição JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Exemplo de corpo da resposta JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
  // envelope properties
}

Atualizar

A operação Atualizar irá atualizar um registro existente. O identificador do registro é especificado na URL.

Note que todo o registro é retornado na resposta. Isso é útil em casos onde alguns campos são criados ou atualizados pelo servidor (como um carimbo de data/hora de atualização do registro).

Método HTTP

• PUT: Usado para uma atualização completa. Todos os parâmetros do registro precisam ser especificados.

• POST: Usado para uma atualização parcial. Apenas os parâmetros obrigatórios do registro precisam ser especificados.

URL de exemplo

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

Corpo da solicitação JSON de exemplo

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Corpo da resposta JSON de exemplo

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
  // envelope properties
}

Deletar

A operação de exclusão irá deletar um registro. O identificador do registro é especificado na URL. Nenhum corpo de solicitação precisa ser enviado para um DELETE.

Método HTTP

DELETE

URL de exemplo

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

Corpo da resposta JSON de exemplo

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Parâmetros de consulta

Obter muitos

No nível da coleção, seu endpoint REST deve suportar os seguintes recursos.

Paginação

Para coleções que contêm muitos registros, muitas vezes é necessário suportar a paginação. Para suportar a paginação, o App Builder define os seguintes parâmetros:

Ordenação

O App Builder pode suportar a ordenação simples de campos.

Filtragem

O App Builder oferece suporte para uma string de filtro de consulta. A string de filtro de consulta suporta um subconjunto da especificação de filtro de string de consulta OData 4.0. Para comparações de strings, caracteres curinga podem ser especificados usando o caractere %.

Operadores

Comparação

Lógico

Limitações

• Nenhum operador aritmético.

• Nenhum operador lógico ou/não.

• Nenhum operador de agrupamento.

• Nenhuma função de consulta.

• Nenhum alias de parâmetro.

Pesquisa

O App Builder fornece um mecanismo para buscar registros em uma coleção. Essa busca opera em todos os campos pesquisáveis do registro.

O App Builder, por padrão, adiciona curingas ao início e ao fim da string de busca.

Convenções de tipo

Tipos JSON

Como regra geral, os desenvolvedores devem preferir usar os tipos JSON nativos embutidos. O App Builder mapeia automaticamente os tipos JSON nativos, portanto, o uso direto de numéricos, booleanos, strings e nulos é encorajado.

Datas

O App Builder codifica datas usando o formato ISO 8601. Todas as datas são serializadas em UTC.

• https://en.wikipedia.org/wiki/ISO_8601

Versionamento

Para lidar com incompatibilidades futuras entre versões da API REST, o App Builder inclui um número de versão diretamente na URL REST.

URL de exemplo

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

Operações Opcionais

Outras operações que podem ser úteis para incluir em uma API REST CRUD.

Novo

A operação nova é usada para retornar os padrões de registro. Isso é utilizado antes de criar um registro para casos em que alguns dados podem ser preenchidos previamente pelo servidor REST.

Método HTTP

• GET

• POST

Exemplo de URL

https://example.com/rest/v1/sales/customers(new)

Exemplo de corpo de resposta JSON

{
  "item": {
    "customerId": null,
    "daysActive": 0
  }
  // envelope properties
}

JSON - Conversão de tabelas relacionais

O App Builder fornece um mecanismo para converter entre a representação interna de tabelas relacionais de dados e o JSON esperado pelos endpoints REST.

Arrays para tabelas

Cada array em uma estrutura JSON é considerado uma tabela relacional separada dentro do App Builder.

Assim, a seguinte conversão se aplicaria a um endpoint chamado "customers(get)":

customers(get) JSON

{
  "count": 2,
  "message": "Sample message",
  "status": 200,
  "items": [
    {
      "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
      "name": "John Henry",
      "address": "130 Plutonium Drive"
    },
    {
      "customerId": "9775de33-08fc-4cd2-98ef-d91f3d5355b1",
      "name": "Sally Keith",
      "address": "4500 Neutrino Road"
    }
  ],
  // envelope properties
}

Estrutura da tabela resultante

customers(get)

customers(get)/items

Escrita de dados

Atualmente, o App Builder suporta apenas a escrita em uma única tabela durante um evento. Como cada array JSON é considerado uma tabela separada, escrever um objeto inteiro que compreende múltiplos arrays em um único evento do App Builder pode não ser suportado.

Como resultado, busque minimizar o uso de arrays JSON sempre que possível, ou suporte a escrita dos arrays em um objeto em um endpoint REST API separado.

Por exemplo, um objeto "customer" pode conter múltiplos endereços. Ter um endpoint para escrever o objeto do cliente e outro endpoint para escrever os endereços permite que o App Builder integre mais facilmente com sua REST API.