Como chamar pontos de extremidade REST

O DAB (Construtor de API de Dados) fornece uma API Web RESTful que permite acessar tabelas, exibições e procedimentos armazenados de um banco de dados conectado. Cada objeto de banco de dados exposto é definido como uma entidade na configuração de runtime.

Por padrão, o DAB hospeda pontos de extremidade REST em:

https://{base_url}/api/{entity}

Observação

Todos os componentes de caminho e parâmetros de consulta são sensíveis a maiúsculas e minúsculas.

Palavras-chave com suporte no construtor de API de Dados

Conceito	REST	Propósito
Projection	$select	Escolher quais campos retornar
Filtragem	$filter	Restringir linhas por condição
Classificação	$orderby	Definir a ordem de classificação
Tamanho da página	$first	Limitar os itens por página
Continuação	$after	Continuar da última página

Estrutura básica

Para chamar uma API REST, construa uma solicitação usando este padrão:

{HTTP method} https://{base_url}/{rest-path}/{entity}

Exemplo de leitura de todos os registros da book entidade:

GET https://localhost:5001/api/book

A resposta é um objeto JSON:

{
  "value": [
    { "id": 1, "title": "Dune" },
    { "id": 2, "title": "Foundation" }
  ]
}

Observação

Por padrão, o DAB retorna até 100 itens por consulta, a menos que configurado de outra forma (runtime.pagination.default-page-size).

Tipos de consulta

Cada entidade REST dá suporte a leituras tanto de coleções quanto de registros únicos.

Operation	Descrição
GET /api/{entity}	Retorna uma lista de registros
GET /api/{entity}/{primary-key-column}/{primary-key-value}	Retorna um registro por chave primária

Exemplo de retorno de um registro:

GET /api/book/id/1010

O exemplo retorna muitos:

GET /api/book

Filtrando resultados

Use o $filter parâmetro de consulta para restringir quais registros são retornados.

GET /api/book?$filter=title eq 'Foundation'

Esta consulta retorna todos os livros cujo título é igual a "Foundation".

Os filtros podem incluir operadores lógicos para consultas mais complexas:

GET /api/book?$filter=year ge 1970 or title eq 'Dune'

Consulte a referência de argumento $filter para operadores com suporte, como eq, ne, lt, le, and, e or.

Classificando resultados

O $orderby parâmetro define como os registros são classificados.

GET /api/book?$orderby=year desc, title asc

Isso retorna livros ordenados por year decrescente, então por title.

Consulte a referência de argumento $orderby para obter mais detalhes.

Limitando resultados {#primeiro-e-depois}

O $first parâmetro limita quantos registros são retornados em uma solicitação.

GET /api/book?$first=5

Isso retorna os cinco primeiros livros, ordenados por chave primária por padrão. Você também pode usar $first=-1 para solicitar o tamanho máximo de página configurado.

Saiba mais na referência de argumento $first.

Resultados contínuos

Para buscar a próxima página, use $after com o token de continuidade da resposta anterior.

GET /api/book?$first=5&$after={continuation-token}

O $after token identifica onde a última consulta terminou. Consulte referência de argumento $after para obter detalhes.

Seleção de campo (projeção)

Use $select para controlar quais campos estão incluídos na resposta.

GET /api/book?$select=id,title,price

Isso retorna apenas as colunas especificadas. Se um campo estiver ausente ou não estiver acessível, o DAB retornará 400 Bad Request.

Consulte $select referência de argumento para obter detalhes.

Modificando dados

A API REST também dá suporte a operações de criação, atualização e exclusão, dependendo das permissões de entidade.

Método	Ação
POST	Criar um novo item
PUT	Substituir um item existente (ou criar se estiver ausente)
PATCH	Atualizar um item existente (ou criar se estiver ausente)
DELETE	Remover um item por chave primária

Exemplo de criação de um novo registro:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes"
}

Exemplo de atualização de um registro existente:

PATCH /api/book/id/2000
Content-type: application/json

{
  "year": 2011,
  "pages": 577
}

Exemplo excluindo um registro:

DELETE /api/book/id/2000