Cara memanggil titik akhir REST

Penyusun API Data (DAB) menyediakan API web RESTful yang memungkinkan Anda mengakses tabel, tampilan, dan prosedur tersimpan dari database yang terhubung. Setiap objek database yang diekspos didefinisikan sebagai entitas dalam konfigurasi runtime.

Secara default, DAB menghosting titik akhir REST di:

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

Nota

Semua komponen jalur dan parameter kueri sensitif terhadap huruf besar/kecil.

Kata kunci yang didukung di penyusun API Data

Konsep	REST	Kegunaan
Proyeksi	$select	Pilih bidang mana yang akan dikembalikan
Penyaringan	$filter	Membatasi baris menurut kondisi
Pengurutan	$orderby	Tentukan urutan pengurutan
Ukuran halaman	$first	Batasi jumlah item per halaman
Kelanjutan	$after	Lanjutkan dari halaman terakhir

Struktur dasar

Untuk memanggil REST API, buat permintaan menggunakan pola ini:

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

Contoh membaca semua rekaman dari book entitas:

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

Responsnya adalah objek JSON dengan value array. Penomoran halaman dan informasi kesalahan hanya muncul jika berlaku.

Nota

Secara default, DAB mengembalikan hingga 100 item per kueri kecuali dikonfigurasi sebaliknya (runtime.pagination.default-page-size).

HTTP

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

Sukses:

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

Berhasil dengan paginasi:

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

Hasil kosong (item tidak ditemukan):

{
  "value": []
}

Nota

Permintaan GET untuk kunci primer yang tidak ada mengembalikan 200 OK dengan array kosong value —bukan 404 Not Found. Periksa array kosong untuk menentukan apakah item ada.

cURL

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

C#

Kelas model berikut mendeserialisasi respons 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; }
}

Panggil API dan deserialisasi respons:

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 ?? [];
}

Python

Berikut adalah kelas data yang memodelkan respons 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

Panggil API dan uraikan respons:

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", [])]

JavaScript

Fungsi berikut memanggil 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 ?? [];
}

Contoh penggunaan:

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

Jenis kueri

Setiap entitas REST mendukung pengumpulan dan pembacaan rekaman tunggal.

Pengoperasian	Deskripsi
GET /api/{entity}	Mengembalikan daftar rekaman
GET /api/{entity}/{primary-key-column}/{primary-key-value}	Mengembalikan satu rekaman menurut kunci primer

Contoh mengembalikan satu rekaman:

GET /api/book/id/1010

Contoh mengembalikan banyak:

GET /api/book

Memfilter hasil

$filter Gunakan parameter kueri untuk membatasi rekaman mana yang dikembalikan.

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

Kueri ini mengembalikan semua buku yang judulnya sama dengan "Foundation."

Filter dapat mencakup operator logis untuk kueri yang lebih kompleks:

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

Untuk informasi selengkapnya, lihat referensi argumen $filter.

Mengurutkan hasil

Parameter $orderby menentukan bagaimana rekaman diurutkan.

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

Ini mengembalikan buku yang diurutkan berdasarkan year menurun, lalu berdasarkan title.

Untuk informasi selengkapnya, lihat referensi argumen $orderby.

Membatasi hasil {#first-and-after}

Parameter $first membatasi berapa banyak rekaman yang dikembalikan dalam satu permintaan.

GET /api/book?$first=5

Ini mengembalikan lima buku pertama, diurutkan berdasarkan kunci primer secara default. Anda juga dapat menggunakan $first=-1 untuk meminta ukuran halaman maksimum yang dikonfigurasi, yang defaultnya adalah 100 item. Konfigurasikan batas ini dengan runtime.pagination.default-page-size dalam file konfigurasi Anda.

Untuk informasi selengkapnya, lihat referensi argumen $first.

Melanjutkan hasil

Untuk mengambil halaman berikutnya, gunakan $after dengan token kelanjutan dari respons sebelumnya.

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

Token $after mengidentifikasi tempat kueri terakhir berakhir. Untuk informasi selengkapnya, lihat referensi argumen $after.

Pemilihan bidang (proyeksi)

Gunakan $select untuk mengontrol bidang mana yang disertakan dalam respons.

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

Ini hanya mengembalikan kolom yang ditentukan. Jika bidang hilang atau tidak dapat diakses, DAB mengembalikan 400 Bad Request.

Untuk informasi selengkapnya, lihat referensi argumen $select.

Memodifikasi data

REST API juga mendukung operasi buat, perbarui, dan hapus tergantung pada izin entitas.

Metode	Action
POST	Membuat item baru
PUT	Ganti item yang sudah ada (atau buat jika hilang)
PATCH	Perbarui item yang sudah ada (atau buat jika hilang)
DELETE	Menghapus item menurut kunci utama

Penting

Perilaku upsert (insert-if-missing) PUT dan PATCH hanya berfungsi ketika database mengizinkan nilai kunci primer eksplisit. Untuk tabel dengan kunci yang dibuat secara otomatis (seperti IDENTITY kolom di SQL Server atau SERIAL di PostgreSQL), PUT atau PATCH ke kunci yang tidak ada mengembalikan 404 Not Found karena database menolak sisipan eksplisit ke dalam kolom yang dibuat secara otomatis. Gunakan POST untuk membuat rekaman pada tabel dengan kunci yang dibuat secara otomatis, atau gunakan PUT dan PATCH tanpa kunci untuk memungkinkan DAB menetapkan kunci secara otomatis.

Membuat rekaman baru

Gunakan POST untuk membuat item baru.

HTTP

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

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

cURL

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

C#

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

Python

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']}")

JavaScript

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}`);
}

Perbarui data yang ada

Gunakan PATCH untuk memperbarui bidang tertentu pada item yang sudah ada.

HTTP

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

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

cURL

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

C#

Petunjuk / Saran

Secara default, DAB menolak bidang di isi permintaan Anda yang tidak ada di database atau yang termasuk dalam URL (seperti bidang kunci utama untuk PATCH dan DELETE). Perilaku ini memerlukan jenis C# terpisah: satu dengan kunci untuk POST dan satu tanpa pembaruan. Untuk menggunakan kembali satu jenis seperti Book untuk semua operasi, atur runtime.rest.request-body-strict ke false dalam konfigurasi Anda.

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

Python

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']}")

JavaScript

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}`);
}

Hapus sebuah catatan

Gunakan DELETE untuk menghapus item menurut kunci primer.

HTTP

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

cURL

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

C#

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

Python

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']}")

JavaScript

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}`);
}

Jalur REST tingkat lanjut dengan subdirektori

Nota

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Jalur REST entitas dapat menyertakan garis miring ke depan untuk membuat segmen URL gaya subdirektori. Konfigurasi ini memungkinkan struktur URL hierarkis yang lebih ekspresif untuk API Anda.

Konfigurasikan jalur subdirektori di properti entitas rest.path :

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

Konfigurasi ini menghasilkan titik akhir:

GET /api/shopping-cart/item

DAB menggunakan pencocokan awalan terpanjang untuk perutean, sehingga jalur yang lebih spesifik dicocokkan sebelum yang lebih pendek. Untuk keamanan, validasi memblokir pola traversal lintasan (seperti ..), garis miring terbalik, dan pemisah yang dikodekan persen.

Untuk informasi selengkapnya, lihat konfigurasi jalur REST.

PUT dan PATCH tanpa kunci untuk kunci primer yang dibuat secara otomatis

Nota

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Ketika semua kolom kunci utama untuk entitas dibuat secara otomatis (misalnya, IDENTITY kolom di SQL Server), Anda dapat mengirim permintaan PUT dan PATCH tanpa menentukan kunci utama di URL. DAB secara otomatis menetapkan kunci selama penyisipan.

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

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

Permintaan ini membuat rekaman baru Book dengan kunci primer yang dibuat secara otomatis.

Aturan untuk operasi tanpa kunci

• Semua kolom kunci primer yang dihilangkan harus dibuat secara otomatis. Jika ada kolom kunci yang dihilangkan tidak dibuat secara otomatis, permintaan gagal.
• Untuk kunci primer komposit, Anda masih harus menyediakan bagian kunci yang tidak dibuat secara otomatis di URL.
• Prosedur tersimpan tidak terpengaruh oleh fitur ini. Mereka terus menggunakan penanganan parameter mereka sendiri.
• Dokumen OpenAPI mencerminkan operasi tanpa kunci pada jalur entitas dasar (misalnya, PUT /api/Book tanpa segmen kunci).

Kompresi respons HTTP

Nota

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

DAB mendukung kompresi respons HTTP untuk mengurangi ukuran payload dan meningkatkan kecepatan transfer. Konfigurasikan kompresi di bagian runtime.compression file konfigurasi Anda:

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

Tingkat kompresi yang tersedia:

Tingkat	Deskripsi
optimal	Menyeimbangkan rasio dan kecepatan kompresi (disarankan untuk sebagian besar skenario)
fastest	Memprioritaskan kecepatan kompresi di atas rasio
none	Menonaktifkan pemadatan

Untuk informasi selengkapnya tentang mengonfigurasi kompresi, lihat konfigurasi kompresi runtime.