Recomendações da API REST no Jitterbit App Builder

Visão geral

Este documento fornece orientação para desenvolvedores que buscam 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 CRUD REST. Muitos dos princípios usados em uma API CRUD serão aplicáveis a outras APIs. No entanto, uma API CRUD provavelmente terá os requisitos mais abrangentes que interagirão 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 independentes de estado.
Os 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 não são seguras, mas são 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.
Operações POST não são seguras nem idempotentes. Por isso, 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 executar 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 recurso são encapsulados em um envelope. Isso permite que o App Builder inclua informações adicionais, como mensagens de eventos e resultados de validação.
As respostas de recursos não são hipermídia: elas não incluem links para outros recursos.

Envoltório

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

Envelope do corpo da solicitação

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

Nome da propriedade	Descrição
item	A payload do endpoint.

Exemplo JSON

{
  "item": {}
}

Envelope do corpo da resposta

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

Nome da propriedade	Descrição
message	A mensagem de sucesso ou falha do evento.
status	Este é o código de status HTTP (duplicado).
validations	Uma matriz de erros/avisos de validação para o endpoint chamado.
item ou itens	A payload do endpoint - um único item ou uma coleção de itens.

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 tem as seguintes propriedades:

Nome da Propriedade	Descrição
message	A mensagem de validação.
severity	A gravidade da validação: error warning information
field	O campo referenciado pela validação.

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, escolherão não implementar certos métodos (por exemplo, um serviço somente leitura implementaria apenas os métodos Get Single/Get Many).

Fique solteiro

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

Método HTTP

PEGAR

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

Pegue muitos

A operação Get Many retorna muitos registros para uma coleção. Muitas vezes, essa operação é usada junto com a paginação, para permitir que uma coleção de registros seja examinada.

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 UI, bem como informe a UI quando o fim da coleção for atingido.

Método HTTP

PEGAR

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 Create criará um novo registro. O identificador para o registro existe dentro do corpo JSON.

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

Método HTTP

PUBLICAR

Exemplo de URL

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

Exemplo de corpo de solicitação JSON

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

Exemplo de corpo de resposta JSON

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

Atualizar

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

Observe que todo o registro é ecoado de volta na resposta. Isso é útil em casos em que alguns campos são criados ou atualizados pelo servidor (como um carimbo de data/hora de atualização de 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.

Exemplo de URL

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

Exemplo de corpo de solicitação JSON

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

Exemplo de corpo de resposta JSON

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

Excluir

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

Método HTTP

EXCLUIR

Exemplo de URL

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

Exemplo de corpo de resposta JSON

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

Parâmetros de consulta

Pegue muitos

No nível de coleção, seu endpoint REST deve oferecer suporte aos seguintes recursos.

Paginação

Para coleções que contêm muitos registros, geralmente é necessário dar suporte à paginação. Para dar suporte à paginação, o App Builder define os seguintes parâmetros:

Parâmetro de consulta	Descrição	Exemplo
$limit	O número máximo de registros a serem recuperados em uma solicitação.	`$limit=10`
$offset	De qual offset de registro a busca deve começar. Offsets são baseados em zero, então especificar 0 buscará o primeiro registro na coleção.	`$offset=10`
$count	Um booleano que indica se uma contagem de coleção deve ser retornada. No App Builder, esse parâmetro é considerado falso por padrão.	`$count=true`

Classificação

O App Builder pode oferecer suporte à classificação simples de campos.

Parâmetro de consulta	Descrição	Exemplo
$sort	Uma lista delimitada por vírgulas de nomes de campos para classificar. Prefixe o nome do campo com um traço (-) para classificar o campo em ordem decrescente. No exemplo fornecido, classifique a coleção por país, decrescente, e companyName, crescente.	`$sort=-country,companyName`

Filtragem

O App Builder fornece suporte para uma string de filtro de consultar. A string de filtro de consultar oferece suporte a um subconjunto da especificação de filtro de string de consultar do OData 4.0. Para comparações de strings, curingas podem ser especificados usando o % personagem.

Parâmetro de consulta	Descrição	Exemplo
$filter	Uma string de consultar no estilo OData 4.0 que filtra dados	`$filter=country eq 'united%'`

Operadores

Comparação

Operador	Descrição	Exemplo
eq	Igual ao valor.	`categoryId eq 42`
neq	Não é igual ao valor.	`categoryId neq 42`
gt	Maior que o valor.	`price gt 100`
lt	Menor que o valor.	`price lt 100`
ge	Maior ou igual ao valor.	`price ge 100`
le	Menor ou igual ao valor.	`price le 100`
in	Corresponde a qualquer valor na lista.	`categoryId in (1, 2, 3)`

Lógico

Operador	Descrição	Exemplo
e	E lógico	`price gt 100 and categoryId in (1,2,3)`

Limitações

Sem operadores aritméticos
Nenhum operador lógico ou/não
Nenhum operador de agrupamento
Nenhuma função de consultar
Nenhum aliases de parâmetro

Procurar

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

Por padrão, o App Builder adiciona curingas ao início e ao fim da sequência de pesquisa.

Parâmetro de consulta	Descrição	Exemplo
$q	Uma string de pesquisa para aplicar a todas as colunas pesquisáveis de um registro.	`$q=hello`

Convenções de tipo

Tipos JSON

Como regra geral, os desenvolvedores devem preferir usar os tipos JSON nativos integrados. O App Builder mapeia automaticamente os tipos JSON nativos, então 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

Controle de versão

Para lidar com futuras incompatibilidades 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 nova operação é usada para retornar padrões de registro. Isso é usado antes de criar um registro para casos em que alguns dados podem ser pré-preenchidos pelo servidor REST.

Método HTTP

OBTER
PUBLICAR.

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 de tabela relacional interna de dados e JSON esperado pelos endpoints REST.

Matrizes para tabelas

Cada matriz em uma estrutura JSON é considerada uma tabela relacional separada no App Builder.

Dessa forma, a seguinte conversão seria aplicada a um endpoint chamado "customers(get)":

Clientes(obter) 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

"clientes(obter)"

Contagem	Mensagem	Status
2	Mensagem de exemplo	200

"clientes(obter)/itens"

customerid	nome	endereço
9775de33-08fc-4cd2-98ef-d91f3d5355b1	Sally Keith	Estrada Neutrino 4500
b603b276-a9bf-4328-88ff-8994176c38d1	John Henry	130 Plutônio Drive

Escrevendo dados

Atualmente, o App Builder só oferece suporte à gravação em uma única tabela durante um evento. Como cada matriz JSON é considerada uma tabela separada, a gravação de um objeto inteiro que compreende várias matrizes em um único evento do App Builder pode não ser suportada.

Como resultado, procure minimizar o uso de matrizes JSON sempre que possível ou ofereça suporte à gravação de matrizes em um objeto em um endpoint da API REST separado.

Por exemplo, um objeto "customer" pode conter vários endereços. Ter um endpoint para escrever o objeto customer e outro endpoint para escrever os endereços permite que o App Builder se integre mais facilmente com sua REST API.