Recomendações da API REST

Visão Geral

Este documento fornece orientação para desenvolvedores que buscam implementar an App Builder API REST compatível.

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 App Builder(paginação, busca, filtragem etc).

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:

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

Envoltório

App Builder os corpos de solicitação e resposta da API REST 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 App Builder o corpo da solicitação da API REST contém estas propriedades de envelope:

Exemplo JSON

{
  "item": {}
}

Envelope do Corpo da Resposta

O App Builder o corpo de resposta da API REST contém estas propriedades de 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 tem 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, 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 App Builder para exibir a contagem de registros na UI, bem como informar 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 oferecer suporte à paginação. Para oferecer suporte à paginação, App Builder define os seguintes parâmetros:

Classificação

App Builder pode suportar classificação simples de campos.

Filtragem

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

Operadores

Comparação

Lógico

| Operador | Descrição | Exemplo |TABLEROWEND| ...TABLEROWEND | 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

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

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

Convenções de Tipo

Tipos JSON

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

Datas

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, 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

App Builder fornece um mecanismo para converter entre a representação de tabela relacional interna de dados e JSON esperado por endpoints REST.

Matrizes para Tabelas

Cada matriz em uma estrutura JSON é considerada uma tabela relacional separada dentro 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)"

"clientes(obter)/itens"

Escrevendo Dados

Atualmente, App Builder suporta somente a 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 uma única App Builder o evento pode não ser suportado.

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 "cliente" pode conter vários endereços. Ter um endpoint para escrever o objeto cliente e outro endpoint para escrever os endereços permite App Builder para integrar mais facilmente com sua API REST.