Recomendações da API REST¶

Visão Geral¶

Este documento fornece orientação para desenvolvedores que desejam implementar uma API REST compatível com Vinyl.

Para os fins deste documento, assumiremos que o desenvolvedor está focado na criação de 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 irão interagir com o Vinyl (paginação, pesquisa, filtragem, etc.).

Princípios de Design RESTful¶

Na medida do possível, a API REST do Vinyl segue estes princípios RESTful:

• Os serviços são apátridas.
• Os Endpoints são modelados como recursos.
• As operações GET são seguras. Uma operação “segura” é aquela que não apresenta efeitos colaterais. Por exemplo, recuperar uma lista de clientes não altera a lista de clientes.
• As 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.
• 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.
• Os tipos de mídia são usados para realizar a negociação de conteúdo. No momento, porém, o Vinyl suporta apenas JSON (application/json) e UTF-8.

O Vinyl não adere a todos os princípios RESTful:

• Os órgãos de solicitação e resposta de recursos são embrulhados em um envelope. Isso permite que o Vinyl inclua informações adicionais, como mensagens de eventos e resultados de validação.
• As respostas dos recursos não são hipermídia: não incluem links para outros recursos.

Envelope¶

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

Solicitar Envelope Corporal¶

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

Exemplo JSON¶

{
  "item": {}
}

Envelope Corporal de Resposta¶

O corpo da resposta da API REST do Vinil 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 à matriz 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 o seu serviço REST deve suportar. É claro que alguns serviços optarão por não implementar determinados métodos (por exemplo, um serviço somente leitura implementaria apenas 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

URL de Exemplo¶

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

Obtenha Muitos¶

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

Se possível, uma contagem dos registros da coleção deverá ser retornada. Isso permite que o Vinyl exiba a contagem de registros na interface do usuário, além de informar a interface do usuário quando o final da coleção for atingido.

Método HTTP¶

PEGAR

URL de Exemplo¶

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 do registro existe no corpo JSON.

Observe que todo o registro é repetido na resposta. Isso é útil nos 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

URL de Exemplo¶

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 do registro é especificado na URL.

Observe que todo o registro é repetido na resposta. Isso é útil nos 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.

URL de Exemplo¶

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 de exclusão excluirá um registro. O identificador do registro é especificado no URL. Nenhum corpo de solicitação precisa ser enviado para DELETE.

Método HTTP¶

EXCLUIR

URL de Exemplo¶

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¶

Obtenha Muitos¶

Ao nível da recolha, o seu endpoint REST deve suportar as seguintes funcionalidades.

Paginação¶

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

Ordenação¶

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

Filtragem¶

O Vinyl fornece suporte para uma string de filtro de consultar. A cadeia de caracteres do filtro de consultar dá suporte a um subconjunto da especificação do filtro de cadeia de caracteres de consultar OData 4.0. Para comparações de strings, os curingas podem ser especificados usando o % personagem.

Operadores¶

Comparação¶

Lógico¶

Limitações¶

• Sem operadores aritméticos
• Nenhum ou/não operadores lógicos
• Sem operadores de agrupamento
• Sem funções de consultar
• Sem aliases de parâmetro

Procurar¶

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

Por padrão, o Vinyl adiciona curingas ao início e ao final da string de pesquisa.

Convenções de Tipo¶

Tipos JSON¶

Como regra geral, os desenvolvedores devem preferir usar os tipos JSON nativos integrados. O Vinyl mapeia automaticamente os tipos JSON nativos, portanto, o uso direto de números, booleanos, strings e nulos é incentivado.

Datas¶

O vinil 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 Vinyl 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 nova operação é usada para retornar padrões de registro. Isso é usado antes da criação de um registro para casos em que alguns dados possam ser pré-preenchidos pelo servidor REST.

Método HTTP¶

• PEGAR
• PUBLICAR.

URL de Exemplo¶

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 Vinyl fornece um mecanismo para converter entre a representação de dados da tabela relacional interna e o JSON esperado pelos endpoints REST.

Matrizes para Tabelas¶

Cada array em uma estrutura JSON é considerada uma tabela relacional separada dentro do Vinyl.

Dessa forma, a conversão a seguir se aplicaria a um endpoint denominado "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"

Gravando Dados¶

Atualmente, o Vinyl só suporta gravação em uma única tabela durante um evento. Como cada array JSON é considerado uma tabela separada, talvez não seja possível gravar um objeto inteiro que inclua vários arrays em um único evento Vinyl.

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

Por exemplo, um objeto “cliente” pode conter vários endereços. Ter um endpoint para escrever o objeto do cliente e outro endpoint para escrever os endereços permite que o Vinyl se integre mais facilmente com sua API REST.