Recomendações da API REST no Jitterbit App Builder

Visão Geral

Este documento fornece orientações para desenvolvedores que desejam implementar uma API REST compatível com o App Builder.

Para os propósitos deste documento, assumiremos 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).

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

• Os corpos de solicitação e resposta de recursos são encapsulados 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.

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 de JSON

{
  "item": {}
}

Envelope do corpo da resposta

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

Exemplo de 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 da resposta. O objeto de validação possui as seguintes propriedades:

Exemplo de 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 de 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 para 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, uma contagem dos registros na coleção deve ser retornada. Isso permite que o App Builder exiba a contagem de registros na interface do usuário, além de informar à interface do usuário quando o final da coleção foi alcançado.

Método HTTP

GET

URL de Exemplo

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

JSON de Exemplo

{
  "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 para o 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

URL de Exemplo

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

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
}

Atualizar

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

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 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 deletar irá excluir um registro. O identificador para o 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 fornece 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 string, curingas podem ser especificados usando o caractere %.

Operadores

Comparação

Lógico

Limitações

• Sem operadores aritméticos
• Sem operadores lógicos or/not
• Sem operadores de agrupamento
• Sem funções de consulta
• Sem aliases de parâmetros

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.

Por padrão, o App Builder 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 é incentivado.

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.

Exemplo de URL

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.