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
Projection	$select	Scegliere i campi da restituire
Filtraggio	$filter	Limitare le righe per condizione
Ordinamento	$orderby	Definire l'ordinamento
Dimensioni 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:

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

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).

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'

Vedere il riferimento all'argomento $filter per gli operatori supportati, come eq, ne, lt, le, and e or.

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 dettagli, consultare il riferimento al parametro $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 le dimensioni massime della pagina configurate.

Altre informazioni sono disponibili nel 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 informazioni dettagliate, vedere 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 informazioni dettagliate, vedere $select riferimento dell'argomento.

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

Esempio di creazione di un nuovo record:

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

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

Esempio di aggiornamento di un record esistente:

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

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

Esempio di eliminazione di un record:

DELETE /api/book/id/2000