Come chiamare gli endpoint REST

Il generatore di API dati (DAB) fornisce un'API Web RESTful che consente di accedere a tabelle, viste e stored procedure da un database connesso. Ogni oggetto di database esposto viene definito come entità nella configurazione di runtime.

Per impostazione predefinita, DAB ospita gli endpoint REST in:

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

Annotazioni

Tutti i componenti del percorso e i parametri di query fanno distinzione tra maiuscole e minuscole.

Parole chiave supportate in Generatore API dati

Concetto	REST	Scopo
Proiezione	$select	Scegliere i campi da restituire
Filtraggio	$filter	Limitare le righe per condizione
Ordinamento	$orderby	Definire l'ordinamento
Dimensioni della pagina	$first	Limitare gli elementi per pagina
Continuazione	$after	Continua dall'ultima pagina

Struttura di base

Per chiamare un'API REST, creare una richiesta usando questo modello:

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

Esempio di lettura di tutti i record dall'entità book :

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

La risposta è un oggetto JSON con una value matrice. Le informazioni sull'impaginazione e sull'errore vengono visualizzate solo quando applicabile.

Annotazioni

Per impostazione predefinita, DAB restituisce fino a 100 elementi per ogni query, a meno che non sia configurato diversamente (runtime.pagination.default-page-size).

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

Successo:

{
  "value": [
    { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
    { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
  ]
}

Paginazione riuscita:

{
  "value": [
    { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
    { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
  ],
  "nextLink": "https://localhost:5001/api/book?$after=WyJCb29rMiJd"
}

Risultato vuoto (elemento non trovato):

{
  "value": []
}

Annotazioni

Una richiesta GET per una chiave primaria inesistente restituisce 200 OK con una matrice vuota value , non 404 Not Found. Verificare la presenza di una matrice vuota per determinare se l'elemento esiste.

curl -X GET "https://localhost:5001/api/book"

Le classi di modello seguenti deserializzano le risposte DAB:

using System.Text.Json.Serialization;

public class DabResponse<T>
{
    [JsonPropertyName("value")]
    public List<T>? Value { get; set; }

    [JsonPropertyName("nextLink")]
    public string? NextLink { get; set; }

    [JsonPropertyName("error")]
    public DabError? Error { get; set; }

    [JsonIgnore]
    public bool IsSuccess => Error is null;

    [JsonIgnore]
    public bool HasNextPage => NextLink is not null;
}

public class DabError
{
    [JsonPropertyName("code")]
    public string Code { get; set; } = string.Empty;

    [JsonPropertyName("message")]
    public string Message { get; set; } = string.Empty;

    [JsonPropertyName("status")]
    public int Status { get; set; }
}

public class Book
{
    [JsonPropertyName("id")]
    public int Id { get; set; }

    [JsonPropertyName("title")]
    public string Title { get; set; } = string.Empty;

    [JsonPropertyName("year")]
    public int? Year { get; set; }

    [JsonPropertyName("pages")]
    public int? Pages { get; set; }
}

Chiamare l'API e deserializzare la risposta:

public async Task<List<Book>> GetBooksAsync()
{
    var response = await httpClient.GetAsync("api/book");
    response.EnsureSuccessStatusCode();
    var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

    if (result?.Error is not null)
    {
        throw new Exception($"{result.Error.Code}: {result.Error.Message}");
    }

    return result?.Value ?? [];
}

Le seguenti classi di dati modellano le risposte DAB:

from dataclasses import dataclass
import requests

@dataclass
class Book:
    id: int
    title: str
    year: int | None = None
    pages: int | None = None

@dataclass
class DabError:
    code: str
    message: str
    status: int

@dataclass
class DabResponse:
    value: list[Book] | None = None
    next_link: str | None = None
    error: DabError | None = None

    @property
    def is_success(self) -> bool:
        return self.error is None

    @property
    def has_next_page(self) -> bool:
        return self.next_link is not None

Chiamare l'API e analizzare la risposta:

def get_books(base_url: str) -> list[Book]:
    response = requests.get(f"{base_url}/api/book")
    response.raise_for_status()
    data = response.json()

    if "error" in data:
        err = data["error"]
        raise Exception(f"{err['code']}: {err['message']}")

    return [Book(**item) for item in data.get("value", [])]

La funzione seguente chiama l'API:

async function getBooks(baseUrl) {
  const response = await fetch(`${baseUrl}/api/book`);
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }
  const data = await response.json();

  if (data.error) {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }

  return data.value ?? [];
}

Sintassi di esempio:

const books = await getBooks("https://localhost:5001");
console.log(`Fetched ${books.length} books from the API.`);

Tipi di query

Ogni entità REST supporta sia letture di collezione che letture singole.

Operation	Descrizione
`GET /api/{entity}`	Restituisce un elenco di record
`GET /api/{entity}/{primary-key-column}/{primary-key-value}`	Restituisce un record per chiave primaria

Esempio che restituisce un record:

GET /api/book/id/1010

Esempio che restituisce un insieme di risultati:

GET /api/book

Filtro dei risultati

Usare il $filter parametro di query per limitare i record restituiti.

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

Questa query restituisce tutti i libri il cui titolo è uguale a "Foundation".

I filtri possono includere operatori logici per query più complesse:

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

Per altre informazioni, vedere il riferimento all'argomento $filter.

Ordinamento dei risultati

Il $orderby parametro definisce la modalità di ordinamento dei record.

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

In questo modo vengono restituiti i libri ordinati in year ordine decrescente, quindi in base a title.

Per ulteriori informazioni, consultare la documentazione sull'argomento $orderby.

Limitazione dei risultati {#first-and-after}

Il $first parametro limita il numero di record restituiti in una richiesta.

GET /api/book?$first=5

Restituisce i primi cinque libri, ordinati per chiave primaria per impostazione predefinita. È anche possibile usare $first=-1 per richiedere la dimensione massima configurata della pagina, che per impostazione predefinita è 100 elementi. Configurare questo limite con runtime.pagination.default-page-size nel file di configurazione.

Per altre informazioni, vedere il riferimento all'argomento $first.

Risultati continui

Per recuperare la pagina successiva, usare $after con il token di continuazione della risposta precedente.

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

Il $after token identifica dove è terminata l'ultima query. Per ulteriori informazioni, vedere il riferimento all'argomento $after.

Selezione dei campi (proiezione)

Usare $select per controllare quali campi sono inclusi nella risposta.

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

Restituisce solo le colonne specificate. Se un campo manca o non è accessibile, DAB restituisce 400 Bad Request.

Per altre informazioni, vedere il riferimento all'argomento $select.

Modifica dei dati

L'API REST supporta anche operazioni di creazione, aggiornamento ed eliminazione a seconda delle autorizzazioni dell'entità.

metodo	Action
`POST`	Creare un nuovo elemento
`PUT`	Sostituire un elemento esistente (o crearne se mancante)
`PATCH`	Aggiornare un elemento esistente o crearne uno se mancante
`DELETE`	Rimuovere un elemento in base alla chiave primaria

Importante

Il comportamento upsert (insert-if-missing) di PUT e PATCH funziona solo quando il database consente valori di chiave primaria espliciti. Per le tabelle con chiavi generate automaticamente, ad esempio le IDENTITY colonne in SQL Server o le SERIAL in PostgreSQL, un tentativo di usare un oggetto o una chiave inesistente restituisce PUT perché il database rifiuta inserimenti diretti in una colonna generata automaticamente. Usare POST per creare record in tabelle con chiavi generate automaticamente o usare PUT senza chiave e PATCH per consentire a DAB di assegnare automaticamente la chiave.

Creare un nuovo record

Usare POST per creare un nuovo elemento.

POST https://localhost:5001/api/book
Content-Type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes",
  "year": 2011,
  "pages": 577
}

curl -X POST "https://localhost:5001/api/book" \
  -H "Content-Type: application/json" \
  -d '{"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}'

var book = new Book
{
    Id = 2000,
    Title = "Leviathan Wakes",
    Year = 2011,
    Pages = 577
};
var response = await httpClient.PostAsJsonAsync("api/book", book);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

book = {"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}
response = requests.post(f"{base_url}/api/book", json=book)
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

const book = { id: 2000, title: "Leviathan Wakes", year: 2011, pages: 577 };
const response = await fetch(`${baseUrl}/api/book`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(book),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Aggiorna un record esistente

Usare PATCH per aggiornare campi specifici in un elemento esistente.

PATCH https://localhost:5001/api/book/id/2000
Content-Type: application/json

{
  "id": 2000,
  "title": "Leviathan Wakes",
  "year": 2011,
  "pages": 577
}

curl -X PATCH "https://localhost:5001/api/book/id/2000" \
  -H "Content-Type: application/json" \
  -d '{"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}'

Suggerimento

Per impostazione predefinita, DAB rifiuta i campi nel corpo della richiesta che non esistono nel database o che appartengono all'URL , ad esempio i campi chiave primaria per PATCH e DELETE. Questo comportamento richiede tipi C# separati: uno con chiavi per POST e uno senza per gli aggiornamenti. Per riutilizzare un singolo tipo Book per tutte le operazioni, impostare runtime.rest.request-body-strict su false nella configurazione.

var book = new Book
{
    Id = 2000,
    Title = "Leviathan Wakes",
    Year = 2011,
    Pages = 577
};
var response = await httpClient.PatchAsJsonAsync("api/book/id/2000", book);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

book = {"id": 2000, "title": "Leviathan Wakes", "year": 2011, "pages": 577}
response = requests.patch(f"{base_url}/api/book/id/2000", json=book)
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

const book = { id: 2000, title: "Leviathan Wakes", year: 2011, pages: 577 };
const response = await fetch(`${baseUrl}/api/book/id/2000`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(book),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Eliminare un record

Usare DELETE per rimuovere un elemento in base alla chiave primaria.

DELETE https://localhost:5001/api/book/id/2000

curl -X DELETE "https://localhost:5001/api/book/id/2000"

var response = await httpClient.DeleteAsync("api/book/id/2000");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<DabResponse<Book>>();

if (result?.Error is not null)
{
    throw new Exception($"{result.Error.Code}: {result.Error.Message}");
}

response = requests.delete(f"{base_url}/api/book/id/2000")
response.raise_for_status()
data = response.json()

if "error" in data:
    err = data["error"]
    raise Exception(f"{err['code']}: {err['message']}")

const response = await fetch(`${baseUrl}/api/book/id/2000`, {
  method: "DELETE",
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

Percorsi REST avanzati con sottodirectory

Annotazioni

La funzionalità Generatore API dati descritta in questa sezione è disponibile nella versione 2.0 e successive. Per altre informazioni, vedere Novità della versione 2.0.

I percorsi REST di entità possono includere slash per creare segmenti URL simili a sottodirectory. Questa configurazione consente strutture di URL gerarchici più espressive per l'API.

Configurare un percorso di sottodirectory nella proprietà dell'entità rest.path :

{
  "entities": {
    "ShoppingCartItem": {
      "source": "dbo.ShoppingCartItem",
      "rest": {
        "path": "shopping-cart/item"
      }
    }
  }
}

Questa configurazione risulta nell'endpoint:

GET /api/shopping-cart/item

DAB usa la corrispondenza dei prefissi più lunghi per il routing, quindi i percorsi più specifici vengono confrontati prima di quelli più brevi. Per la sicurezza, la convalida blocca i modelli di attraversamento del percorso (ad esempio ..), le barre rovesciate e i separatori con codifica percentuale.

Per altre informazioni, vedere la configurazione del percorso REST.

PUT senza chiave e PATCH per le chiavi primarie generate automaticamente

Annotazioni

La funzionalità Generatore API dati descritta in questa sezione è disponibile nella versione 2.0 e successive. Per altre informazioni, vedere Novità della versione 2.0.

Quando tutte le colonne chiave primaria per un'entità vengono generate automaticamente (ad esempio, IDENTITY colonne in SQL Server), è possibile inviare PUT e PATCH richiedere senza specificare una chiave primaria nell'URL. DAB assegna automaticamente la chiave durante l'inserimento.

PUT /api/Book
Content-Type: application/json

{
  "title": "My New Book",
  "publisher_id": 1234
}

Questa richiesta crea un nuovo Book record con una chiave primaria generata automaticamente.

Regole per le operazioni senza chiave

Tutte le colonne chiave primaria omesse devono essere generate automaticamente. Se una colonna chiave omessa non viene generata automaticamente, la richiesta ha esito negativo.
Per le chiavi primarie composite, è comunque necessario specificare tutte le parti non generate automaticamente della chiave nell'URL.
Le stored procedure non sono interessate da questa funzionalità. Continuano a usare la gestione dei propri parametri.
Il documento OpenAPI riflette le operazioni senza chiave sul percorso dell'entità di base, PUT /api/Book ad esempio senza segmenti chiave.

Compressione della risposta HTTP

Annotazioni

La funzionalità Generatore API dati descritta in questa sezione è disponibile nella versione 2.0 e successive. Per altre informazioni, vedere Novità della versione 2.0.

DAB supporta la compressione delle risposte HTTP per ridurre le dimensioni del payload e migliorare la velocità di trasferimento. Configurare la compressione nella runtime.compression sezione del file di configurazione:

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

Livelli di compressione disponibili:

livello	Descrizione
`optimal`	Bilancia il rapporto di compressione e la velocità (consigliato per la maggior parte degli scenari)
`fastest`	Assegna priorità alla velocità di compressione rispetto al rapporto
`none`	Disabilita la compressione

Per altre informazioni sulla configurazione della compressione, vedere Configurazione della compressione di runtime.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-22

Come chiamare gli endpoint REST

Parole chiave supportate in Generatore API dati

Struttura di base

Tipi di query

Filtro dei risultati

Ordinamento dei risultati

Limitazione dei risultati {#first-and-after}

Risultati continui

Selezione dei campi (proiezione)

Modifica dei dati

Creare un nuovo record

Aggiorna un record esistente

Eliminare un record

Percorsi REST avanzati con sottodirectory

PUT senza chiave e PATCH per le chiavi primarie generate automaticamente

Regole per le operazioni senza chiave

Compressione della risposta HTTP

Commenti e suggerimenti

Risorse aggiuntive