API REST¶

Visão Geral¶

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

Aplicativos Como Serviços da Web¶

O ambiente de design do Vinyl é organizado em torno do conceito de aplicação. Embora os aplicativos normalmente descrevam uma interface de usuário, os aplicativos possuem diversas propriedades que também são aplicáveis aos serviços da Web:

• Os aplicativos fornecem acesso a múltiplas fontes de dados.
• Os grupos recebem privilégios para um aplicativo.

O Vinyl estende o conceito de aplicativo para incluir serviços web. Especificamente, os desenvolvedores têm a capacidade de definir um endpoint para um aplicativo. Por exemplo, o endpoint do aplicativo Vendas pode ser vendas. O URI correspondente pode ser assim:

• https://example.com/Vinyl/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 termos de Vinyl, um objeto de dados é representado como uma coleção com linhas individuais representadas como itens nessa coleção.

Assim como o próprio serviço, o desenvolvedor determina o endpoint do objeto de dados. Por exemplo, o objeto de dados Clientes pode ter um endpoint de clientes. Nesse caso, o URI correspondente pode ser assim:

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

O URI para um item específico (linha) pode ser assim:

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

A chave primária aparece no caminho do URI.

As chaves primárias compostas podem ser especificadas separando as chaves com uma vírgula:

• https://example.com/Vinyl/rest/v1/sales/customers/abc,def

Eventos Como Métodos HTTP¶

REST define um conjunto de operações correspondentes aos métodos HTTP. A API REST do Vinyl suporta os seguintes métodos HTTP:

• GET /collection - Recupera os itens 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 da coleção. Isso mapeia para o evento Update.
• DELETE /collection/item - Exclui um item da coleção. Isso mapeia para o evento DELETE.

A API REST do Vinyl não suporta atualmente os seguintes métodos HTTP:

• HEAD - O método HEAD permite que os consumidores recuperem os cabeçalhos de resposta HTTP. Neste momento o Vinyl não apoia esta operação.
• OPÇÕES - O método OPTIONS permite que os consumidores determinem quais métodos são suportados.
• PUT (coleção ou item) - O método PUT permite ao consumidor criar um item (ao endereçar a coleção) ou atualizar um item (ao endereçar o item). Contudo, como PUT é idempotente, 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. Atualmente, isso é suportado por meio de um POST. Normalmente, o PATCH usa um formato específico do patch, complicando a implementação.

Nem todos os eventos de Vinyl podem ser publicados:

• Novo - O evento Novo do Vinyl cria uma linha não persistente, aplicando quaisquer padrões. Os consumidores não podem invocar o evento Novo.
• Mudança - As interações com a UI invocam um pseudoevento que executa padrões e validações sem persistir nas 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, estes não podem ser mapeados para métodos de recursos.

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:

• As respostas dos recursos são embrulhadas 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.

Convenções de URI REST¶

No nível da coleção, o método GET oferece suporte aos seguintes recursos:

• Paginação via $offset e $limit parâmetros. O limite padrão é 10; o limite máximo é 100.
• Classificando através de um $sort parâmetro. O $sort O parâmetro pode receber uma lista delimitada por vírgulas de nomes de campos. Coloque um traço (-) no nome do campo 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 nomedaempresa, em ordem crescente.
• Seleção através de um $fields parâmetro. O $fields parâmetro pode receber uma lista delimitada por vírgulas de nomes de campos (por exemplo $fields=customerId,country). Especifique o asterisco (*) para recuperar todos os campos de recursos (por exemplo, $fields=*).
• Pesquisando por palavra-chave através de um $q parâmetro. O $q O 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 substring serão retornadas (por exemplo $q=miami). Observe que a correspondência não diferencia maiúsculas de minúsculas.
• Filtragem através de comparações simples de igualdade. Para limitar os resultados, especifique o nome e o valor do campo (por exemplo countryId=USA).
• Contar através do $count parâmetro. Por padrão, o Vinyl não retornará uma contagem total do número de itens da coleção. Para incluir a contagem, anexe o parâmetro de contagem (por exemplo $count=true).

Convenções para parâmetros:

• Os parâmetros que se referem aos campos de recursos não são prefixados.
• Os 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 informativos 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 o validationIds fornecido como o valor de um cabeçalho X-Vinyl-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-Vinyl-Ignore-Warnings: "8d20b593-aa41-4bbb-8bee-58f17ac2bf32", "6bad40b7-2504-4243-9e90-100bcc7bfd13"

Problemas Conhecidos e Limitações¶

• Campos binários, como arquivos, não são suportados atualmente.
• O único tipo de conteúdo compatível é JSON (application/json).
• A única codificação de texto suportada é UTF-8.
• As coleções estão limitadas à devolução de 100 itens por vez.
• Chaves primárias compostas não podem conter vírgulas.
• Somente a filtragem por meio de comparações simples de igualdade é suportada.