API REST¶

Visão Geral¶

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

Aplicações Como Serviços Web¶

O App Builder o ambiente de design é organizado em torno do conceito de um aplicativo. Embora os aplicativos normalmente descrevam uma interface de usuário, os aplicativos têm várias propriedades que também são aplicáveis a serviços web:

Os aplicativos fornecem acesso a diversas fontes de dados.
Grupos recebem privilégios para um aplicativo.

App Builder estende o conceito de um aplicativo para incluir serviços web. Especificamente, os desenvolvedores têm a capacidade de definir um endpoint para um aplicativo. Por exemplo, o endpoint para o aplicativo Sales pode ser sales. O URI correspondente pode ter esta aparência:

https://example.com/App Builder/rest/v1/sales

Objetos de Dados Como Recursos¶

O princípio organizador do REST é o conceito de "recurso". Os recursos podem representar uma coleção de itens ou um único item. Em App Builder termos, 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 Customers pode ter um endpoint de customers. Nesse caso, o URI correspondente pode ter a seguinte aparência:

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

O URI para um item específico (linha) pode ser parecido com este:

https://example.com/App Builder/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/App Builder/rest/v1/sales/customers/abc,def

Eventos Como Métodos HTTP¶

REST define um conjunto de operações correspondentes aos métodos HTTP. App Builder a API REST do 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.

App Builder a API REST do não oferece suporte aos seguintes métodos HTTP:

HEAD - O método HEAD permite que os consumidores recuperem os cabeçalhos de resposta HTTP. No momento, App Builder não suporta esta operação.
OPÇÕES - O método OPÇÕES 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, 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 por meio de um POST. Normalmente, o PATCH usa um formato específico de patch, complicando a implementação.

Nem todos App Builder eventos podem ser publicados:

Novo - App Builder o evento New do cria uma linha não persistente, aplicando quaisquer padrões. Os consumidores não podem invocar o evento New.
Change - Interações com a UI invocam um pseudoevento 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, eles não podem ser mapeados para métodos de recursos.

Princípios de Design RESTful¶

Na medida do possível, App Builder a API REST do 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.
Os tipos de mídia são usados para executar a negociação de conteúdo. No momento, no entanto, App Builder suporta apenas JSON (application/json) e UTF-8.

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

As respostas de recursos são encapsuladas em um envelope. Isso permite App Builder para incluir informações adicionais, como mensagens de eventos e resultados de validação.
Respostas de recursos não são hipermídia: elas não incluem links para outros recursos.

Convenções REST URI¶

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

Paginação via $offset e $limit parâmetros. O limite padrão é 10; o limite máximo é 100.
Classificando por meio de um $sort parâmetro. O $sort parâmetro pode receber uma lista delimitada por vírgulas de nomes de campos. Prefixe o nome do campo com um traço (-) para classificar o campo em ordem decrescente. Por exemplo, a especificação de classificação $sort=-country,companyName classificaria a coleção por país, em ordem decrescente, e companyName, em ordem crescente.
Seleção via $fields parâmetro. O $fields o parâmetro pode receber uma lista de nomes de campos delimitada por vírgulas (por exemplo $fields=customerId,country). Especifica o asterisco (*) para recuperar todos os campos de recursos (por exemplo $fields=*).
Pesquisa por palavra-chave através de um $q parâmetro. O $q parâmetro recebe uma string e tenta corresponder aos valores da coluna. Quaisquer linhas da tabela que tenham pelo menos um valor de coluna que contenha o parâmetro $q como uma substring serão retornadas (por exemplo, $q=miami). Note que a correspondência não diferencia maiúsculas de minúsculas.
Filtragem por meio de comparações simples de igualdade. Para limitar os resultados, especifique o nome e o valor do campo (por exemplo, countryId=USA).
Contagem através do $count parâmetro. Por padrã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 count (por exemplo, $count=true).

Convenções para parâmetros:

Parâmetros que se referem a campos de recursos não são prefixados.
Parâmetros que operam na própria coleção são prefixados com um cifrão ($).

Validação¶

Um evento pode retornar um ou mais erros, avisos ou resultados de validação informativa 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ê quiser ignorar um aviso, inclua os validationIds fornecidos como o valor de um X-App Builder cabeçalho -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-App Builder-Ignore-Warnings: "8d20b593-aa41-4bbb-8bee-58f17ac2bf32", "6bad40b7-2504-4243-9e90-100bcc7bfd13"

Problemas e Limitações Conhecidos¶

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.
As coleções são limitadas a retornar 100 itens por vez.
Chaves primárias compostas não podem conter vírgulas.
Apenas filtragem por meio de comparações de igualdade simples é suportada.