Tutorial: Membuat API web berbasis pengontrol dengan ASP.NET Core

Oleh Tim Deschryver dan Rick Anderson

Tutorial ini mengajarkan dasar-dasar membangun API web berbasis pengontrol yang menggunakan database. Pendekatan lain untuk membuat API di ASP.NET Core adalah membuat API minimal. Untuk bantuan dalam memilih antara API minimal dan API berbasis pengontrol, lihat Gambaran umum API. Untuk tutorial tentang membuat API minimal, lihat Tutorial: Membuat API minimal dengan ASP.NET Core.

Overview

Tutorial ini membuat API berikut:

API	Description	Isi dari permintaan	Isi respons
GET /api/todoitems	Dapatkan semua daftar tugas	None	Deretan tugas yang harus dilakukan
GET /api/todoitems/{id}	Dapatkan item berdasarkan ID	None	Item yang harus dilakukan
POST /api/todoitems	Menambahkan item baru	Item yang harus dilakukan	Item yang harus dilakukan
PUT /api/todoitems/{id}	Memperbarui item yang sudah ada	Item yang harus dilakukan	None
DELETE /api/todoitems/{id}	Hapus barang	None	None

Diagram berikut menunjukkan desain aplikasi.

Prerequisites

Visual Studio

• Visual Studio 2022 dengan beban kerja pengembangan ASP.NET dan web .

  

Visual Studio Code

• Visual Studio Code
• C# Dev Kit untuk Visual Studio Code
• .NET 9 SDK

Anda dapat mengikuti instruksi Visual Studio Code di macOS, Linux, atau Windows. Perubahan mungkin diperlukan jika Anda menggunakan lingkungan pengembangan terintegrasi (IDE) selain Visual Studio Code.

Membuat proyek API Web

Visual Studio

• Pada menu File, pilih Proyek>Baru.
• Masukkan API Web di kotak pencarian.
• Pilih templat ASP.NET Core Web API dan pilih Berikutnya.
• Dalam dialog Konfigurasikan proyek baru Anda, beri nama proyek TodoApi dan pilih Berikutnya.
• Dalam dialog Informasi Tambahan:
  • Pastikan Kerangka Kerja adalah .NET 9.0 (Dukungan Standar).
  • Konfirmasikan kotak centang untuk Mengaktifkan dukungan OpenAPI dicentang.
  • Konfirmasikan kotak centang untuk Gunakan pengontrol (hapus centang untuk menggunakan API minimal) dicentang.
  • Pilih Buat.

Menambahkan paket NuGet

Paket NuGet harus ditambahkan untuk mendukung database yang digunakan dalam tutorial ini.

• Dari menu Alat, pilih Pengelola > Paket NuGet Kelola Paket NuGet untuk Solusi.
• Pilih tab Telusuri.
• Masukkan Microsoft.EntityFrameworkCore.InMemory di kotak pencarian, lalu pilih Microsoft.EntityFrameworkCore.InMemory.
• Pilih kotak centang Proyek di panel kanan lalu pilih Instal.

Visual Studio Code

• Buka terminal yang terintegrasi.

• Ubah direktori (cd) ke folder yang akan berisi folder proyek.

• Jalankan perintah berikut:

  dotnet new webapi --use-controllers -o TodoApi
  cd TodoApi
  dotnet add package Microsoft.EntityFrameworkCore.InMemory
  code -r .
  

  Perintah ini:

  • Buat proyek API web baru dan buka di Visual Studio Code.
  • Tambahkan paket NuGet yang diperlukan untuk bagian berikutnya.
  • Buka folder TodoApi dalam instans Visual Studio Code saat ini.

Visual Studio Code mungkin menampilkan kotak dialog yang menanyakan: Apakah Anda mempercayai penulis file di folder ini?

• Jika Anda mempercayai semua file di folder induk, pilih Percayai penulis semua file di folder induk.
• Pilih Ya, saya mempercayai penulis karena folder proyek memiliki file yang dihasilkan oleh .NET.
• Saat Visual Studio Code meminta Anda menambahkan aset untuk membangun dan men-debug proyek, pilih Ya. Jika Visual Studio Code tidak menawarkan untuk menambahkan aset build dan debug, pilih Tampilkan>Palet Perintah dan ketikkan ".NET" ke dalam kotak pencarian. Dari daftar perintah, pilih perintah .NET: Generate Assets for Build and Debug.

Visual Studio Code menambahkan folder .vscode dengan file launch.json dan tasks.json yang dihasilkan.

Note

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bawah Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Jalankan proyek

Templat proyek membuat WeatherForecast API dengan dukungan untuk OpenAPI.

Visual Studio

Tekan Ctrl+F5 untuk menjalankan tanpa debugger.

Visual Studio menampilkan dialog berikut saat proyek belum dikonfigurasi untuk menggunakan SSL:

Pilih Ya jika Anda mempercayai sertifikat IIS Express SSL.

Dialog berikut ditampilkan:

Pilih Ya jika Anda setuju untuk mempercayai sertifikat pengembangan tersebut.

Untuk informasi mengenai cara mempercayai browser Firefox, lihat Kesalahan sertifikat Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio meluncurkan jendela terminal dan menampilkan URL aplikasi yang sedang berjalan. API dihosting di https://localhost:<port>, di mana <port> adalah nomor port yang dipilih secara acak yang ditetapkan pada pembuatan proyek.

...
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: https://localhost:7260
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: http://localhost:7261
info: Microsoft.Hosting.Lifetime[0]
   Application started. Press Ctrl+C to shut down.
...

Ctrl+klik URL HTTPS di output untuk menguji aplikasi web di browser. Tidak ada titik akhir di https://localhost:<port>, sehingga browser mengembalikan HTTP 404 Tidak Ditemukan.

Tambahkan /weatherforecast ke URL untuk menguji API WeatherForecast. Browser menampilkan JSON yang mirip dengan contoh berikut:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Visual Studio Code

• Percayai sertifikat pengembangan HTTPS dengan menjalankan perintah berikut:

  dotnet dev-certs https --trust
  

  Perintah sebelumnya menampilkan dialog berikut, asalkan sertifikat sebelumnya tidak tepercaya:

  

• Pilih Ya jika Anda setuju untuk mempercayai sertifikat pengembangan tersebut.

  Untuk informasi selengkapnya, lihat bagian Percayai sertifikat pengembangan ASP.NET Core HTTPS di artikel Memberlakukan SSL .

Untuk informasi mengenai cara mempercayai browser Firefox, lihat Kesalahan sertifikat Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Jalankan aplikasi:

• Jalankan perintah berikut untuk memulai aplikasi di https profil:

  dotnet run --launch-profile https
  

Output menunjukkan pesan yang mirip dengan yang berikut ini, menunjukkan bahwa aplikasi sedang berjalan dan menunggu permintaan:

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

• Ctrl+klik URL HTTPS di output untuk menguji aplikasi web di browser.

• Browser default diluncurkan ke https://localhost:<port>, di mana <port> adalah nomor port yang dipilih secara acak yang ditampilkan dalam output. Tidak ada titik akhir di https://localhost:<port>, sehingga browser mengembalikan HTTP 404 Tidak Ditemukan.

• Tambahkan /weatherforecast ke URL untuk menguji API WeatherForecast. Browser menampilkan JSON yang mirip dengan contoh berikut:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

• Setelah menguji aplikasi web menggunakan instruksi berikut, tekan Ctrl+C di terminal terintegrasi untuk menutupnya.

Menguji proyek

Visual Studio

Tutorial ini menggunakan file Endpoints Explorer dan .http untuk menguji API.

Visual Studio Code

Membuat UI pengujian API dengan Swagger

Ada banyak alat pengujian API web yang tersedia untuk dipilih, dan Anda dapat mengikuti langkah-langkah pengujian API pengantar tutorial ini dengan alat pilihan Anda.

Tutorial ini menggunakan paket .NET NSwag.AspNetCore, yang mengintegrasikan alat Swagger untuk menghasilkan UI pengujian yang mematuhi spesifikasi OpenAPI:

• NSwag: Pustaka .NET yang mengintegrasikan Swagger langsung ke aplikasi ASP.NET Core, menyediakan middleware dan konfigurasi.
• Swagger: Sekumpulan alat sumber terbuka seperti OpenAPIGenerator dan SwaggerUI yang menghasilkan halaman pengujian API yang mengikuti spesifikasi OpenAPI.
• Spesifikasi OpenAPI: Dokumen yang menjelaskan kemampuan API, berdasarkan XML dan anotasi atribut dalam pengontrol dan model.

Untuk informasi selengkapnya tentang menggunakan OpenAPI dan NSwag dengan ASP.NET, lihat dokumentasi API web ASP.NET Core dengan Swagger / OpenAPI.

Menginstal perangkat Swagger

• Jalankan perintah berikut:

  dotnet add package NSwag.AspNetCore
  

Perintah sebelumnya menambahkan paket NSwag.AspNetCore , yang berisi alat untuk menghasilkan dokumen dan UI Swagger. Karena proyek kami menggunakan OpenAPI, kami hanya menggunakan paket NSwag untuk menghasilkan UI Swagger.

Mengonfigurasi middleware Swagger

• Di Program.cs, tambahkan kode yang disorot berikut:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}

Kode sebelumnya memungkinkan middleware Swagger untuk melayani dokumen JSON yang dihasilkan menggunakan antarmuka pengguna Swagger. Swagger hanya diaktifkan di lingkungan pengembangan. Mengaktifkan Swagger di lingkungan produksi dapat mengekspos detail yang berpotensi sensitif tentang struktur dan implementasi API.

Aplikasi ini menggunakan dokumen OpenAPI yang dihasilkan oleh OpenApi, yang terletak di /openapi/v1.json, untuk menghasilkan UI. Lihat spesifikasi OpenAPI yang dihasilkan untuk API WeatherForecast saat proyek berjalan dengan menavigasi ke https://localhost:<port>/openapi/v1.json di browser Anda.

Spesifikasi OpenAPI adalah dokumen dalam format JSON yang menjelaskan struktur dan kemampuan API Anda, termasuk titik akhir, format permintaan/respons, parameter, dan banyak lagi. Ini pada dasarnya adalah cetak biru API Anda yang dapat digunakan oleh berbagai alat untuk memahami dan berinteraksi dengan API Anda.

Menambahkan kelas model

Model adalah sekumpulan kelas yang mewakili data yang dikelola aplikasi. Model untuk aplikasi ini adalah TodoItem kelas.

Visual Studio

• Di Penjelajah Solusi, klik kanan pada proyek. Pilih Tambahkan>Folder Baru. Beri nama folder Models.
• Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoItem dan pilih Tambahkan.
• Ganti kode templat dengan yang berikut ini:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Visual Studio Code

• Tambahkan folder bernama Models.
• TodoItem.cs Tambahkan file ke Models folder dengan kode berikut:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Properti Id berfungsi sebagai kunci unik dalam database relasional.

Kelas model dapat ditempatkan di mana saja dalam proyek, tetapi direktori Models digunakan menurut kebiasaan.

Tambahkan konteks database

Konteks database adalah kelas utama yang mengoordinasikan fungsionalitas Kerangka Kerja Entitas untuk model data. Kelas ini dibuat dengan menurunkan dari kelas Microsoft.EntityFrameworkCore.DbContext.

Visual Studio

• Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoContext dan klik Tambahkan.

• Masukkan kode berikut:

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

Visual Studio Code

• TodoContext.cs Tambahkan file ke Models folder .

• Masukkan kode berikut:

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

Daftarkan konteks basis data

Dalam ASP.NET Core, layanan seperti konteks DB harus terdaftar dengan kontainer injeksi dependensi (DI ). Kontainer menyediakan layanan ke pengontrol.

Perbarui Program.cs dengan kode yang disorot berikut:

Visual Studio

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Visual Studio Code

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));

// <snippet_UseSwagger>
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}
// </snippet_UseSwagger>

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Kode sebelumnya:

• Menambahkan using direktif.
• Menambahkan konteks database ke kontainer DI.
• Menentukan bahwa konteks database akan menggunakan database dalam memori.

Membangun pengontrol

Visual Studio

• Klik kanan folder Controllers.

• Pilih Tambahkan>New Scaffolded Item.

• Pilih Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas, lalu pilih Tambahkan.

• Dalam dialog Tambahkan Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas :

  • Pilih TodoItem (TodoApi.Models) di kelas Model.
  • Pilih TodoContext (TodoApi.Models) di kelas konteks data.
  • Pilih Tambahkan.

  Jika operasi perancah gagal, pilih Tambahkan untuk mencoba perancah untuk kedua kalinya.

Langkah ini menambahkan paket Microsoft.VisualStudio.Web.CodeGeneration.Design dan Microsoft.EntityFrameworkCore.Tools NuGet ke proyek. Paket-paket ini diperlukan untuk perancangan.

Visual Studio Code

Pastikan bahwa semua perubahan Anda hingga saat ini sudah disimpan.

• Klik kanan (atau Klik perintah pada macOS) proyek TodoAPI dan pilih Buka di Terminal. Terminal terbuka di TodoAPI folder proyek. Jalankan perintah berikut:

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet tool uninstall -g dotnet-aspnet-codegenerator
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet tool update -g dotnet-aspnet-codegenerator

Perintah sebelumnya:

• Tambahkan paket NuGet yang diperlukan untuk perancah.
• Instal mesin perancah (dotnet-aspnet-codegenerator) setelah menghapus instalasi versi sebelumnya jika ada.

Untuk Linux, tambahkan direktori alat .NET ke jalur sistem dengan perintah berikut:

echo 'export PATH=$HOME/.dotnet/tools:$PATH' >> ~/.bashrc
source ~/.bashrc

Note

Secara default arsitektur biner .NET yang akan diinstal mewakili arsitektur OS yang sedang berjalan. Untuk menentukan arsitektur OS yang berbeda, lihat penginstalan alat dotnet, opsi --arch. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #29262.

Bangun proyek.

Jalankan perintah berikut:

dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

Perintah sebelumnya membangun perancah TodoItemsController.

Kode yang dihasilkan:

• Menandai kelas dengan [ApiController] atribut . Atribut ini menunjukkan bahwa pengontrol merespons permintaan API web. Untuk informasi tentang perilaku tertentu yang diaktifkan atribut, lihat Membuat API web dengan ASP.NET Core.
• Menggunakan DI untuk menyuntikkan konteks database (TodoContext) ke pengontrol. Konteks database digunakan dalam setiap metode CRUD di pengontrol.

Templat ASP.NET Core untuk:

• Pengontrol yang memiliki tampilan menyertakan [action] dalam template jalur.
• Pengontrol API tidak menyertakan [action] dalam templat rute.

[action] Saat token tidak berada dalam templat rute, nama tindakan (nama metode) tidak disertakan dalam titik akhir. Artinya, nama metode yang terkait dengan aksi tidak digunakan dalam rute yang sesuai.

Memperbarui metode pembuatan PostTodoItem

Perbarui pernyataan pengembalian dalam PostTodoItem untuk menggunakan operator nameof :

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Kode sebelumnya adalah metode HTTP POST, seperti yang ditunjukkan oleh atribut [HttpPost]. Metode ini mendapatkan nilai dari TodoItem isi permintaan HTTP.

Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Metode CreatedAtAction:

• Mengembalikan kode status HTTP 201 jika berhasil. HTTP 201 adalah respons standar untuk HTTP POST metode yang membuat sumber daya baru di server.
• Menambahkan header Lokasi ke respons. Header Location menentukan URI dari item tugas yang baru dibuat. Untuk informasi selengkapnya, lihat 10.2.2 201 Dibuat.
• Merujuk pada tindakan GetTodoItem untuk membuat URI header Location. Kata kunci C# nameof digunakan untuk menghindari hard-coding nama tindakan saat memanggil CreatedAtAction.

Uji PostTodoItem

Visual Studio

• Pilih Lihat>Windows Lainnya>Penjelajah Titik Akhir.

• Klik kanan titik akhir POST dan pilih Buat permintaan.

  

  File baru dibuat di folder proyek bernama TodoApi.http, dengan konten yang mirip dengan contoh berikut:

  @TodoApi_HostAddress = https://localhost:49738
  
  POST {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

  • Baris pertama membuat variabel yang digunakan untuk semua titik akhir.
  • Baris berikutnya menentukan permintaan POST.
  • Baris setelah baris permintaan POST menentukan header, dan tempat penampung untuk isi permintaan.
  • Garis dengan hashtag tiga kali (###) berfungsi sebagai pemisah permintaan: yang datang setelahnya adalah untuk permintaan yang berbeda.

• Permintaan POST mengharapkan objek TodoItem. Untuk menentukan todo, ganti komentar //TodoItem dengan JSON berikut:

  {
    "name": "walk dog",
    "isComplete": true
  }
  

  File TodoApi.http sekarang akan terlihat seperti contoh berikut, tetapi dengan nomor port Anda:

  @TodoApi_HostAddress = https://localhost:7260
  
  Post {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    "name": "walk dog",
    "isComplete": true
  }
  
  ###
  

• Jalankan aplikasi.

• Pilih tautan Kirim permintaan yang berada di atas POST baris permintaan.

  

  Permintaan POST dikirim ke aplikasi dan respons ditampilkan di panel Respons .

  

Visual Studio Code

• Dengan aplikasi yang masih berjalan, di browser, navigasikan ke https://localhost:<port>/swagger untuk menampilkan halaman pengujian API yang dihasilkan oleh Swagger. Klik TodoItems untuk memperluas operasi.

  

• Pada halaman pengujian API Swagger, pilih Posting /api/todoitems>Cobalah.

• Perhatikan bahwa bidang Isi permintaan berisi format contoh yang dihasilkan yang mencerminkan parameter untuk API.

• Dalam isi permintaan masukkan JSON untuk item yang harus dilakukan, tanpa menentukan opsional id:

  {
    "name": "walk dog",
    "isComplete": true
  }
  

• Pilih Jalankan.

  

• Swagger menyediakan panel Respons di bawah tombol Jalankan .

  

Perhatikan beberapa detail yang berguna:

• cURL: Swagger menyediakan contoh perintah cURL dalam sintaks Unix/Linux, yang dapat dijalankan di baris perintah dengan shell bash apa pun yang menggunakan sintaks Unix/Linux, termasuk Git Bash dari Git untuk Windows.
• URL Permintaan: Representasi yang disederhanakan dari permintaan HTTP yang dibuat oleh kode JavaScript UI Swagger untuk panggilan API. Permintaan aktual dapat menyertakan detail seperti header dan parameter kueri dan isi permintaan.
• Respons server: Menyertakan isi respons dan header. Isi respons menunjukkan id diatur ke 1.
• Kode Respons: Kode status 201 HTTP dikembalikan, menunjukkan bahwa permintaan berhasil diproses dan menghasilkan pembuatan sumber daya baru.

Menguji URI lokasi header

Visual Studio

Uji aplikasi dengan memanggil endpoint GET dari browser atau dengan menggunakan Endpoints Explorer. Langkah-langkah berikut adalah untuk Endpoints Explorer.

• Di Endpoints Explorer, klik kanan titik akhir GET pertama, dan pilih Generate request.

  Konten berikut ditambahkan ke TodoApi.http file:

  GET {{TodoApi_HostAddress}}/api/todoitems
  
  ###
  

• Pilih tautan Kirim permintaan yang berada di atas baris permintaan baru GET .

  Permintaan GET dikirim ke aplikasi dan respons ditampilkan di panel Respons .

• Isi respons mirip dengan JSON berikut:

  [
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true
    }
  ]
  

• Di Penjelajah Titik Akhir, klik /api/todoitems/{id} kanan titik akhir GET dan pilih Hasilkan permintaan. Konten berikut ditambahkan ke TodoApi.http file:

  @id=0
  GET {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Tetapkan {@id} ke 1 (bukan 0).

• Pilih tautan Kirim permintaan yang berada di atas baris permintaan GET baru.

  Permintaan GET dikirim ke aplikasi dan respons ditampilkan di panel Respons .

• Isi respons mirip dengan JSON berikut:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

Visual Studio Code

Uji aplikasi dengan memanggil endpoint dari browser atau Swagger.

• Di Swagger pilih GET /api/todoitems>Cobalah>Jalankan.

• Atau, panggil GET /api/todoitems dari browser dengan memasukkan URI https://localhost:<port>/api/todoitems. Misalnya: https://localhost:7260/api/todoitems

Panggilan untuk GET /api/todoitems menghasilkan respons yang mirip dengan yang berikut ini:

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

• Panggil GET /api/todoitems/{id} di Swagger untuk mengembalikan data dari id tertentu:

  • Pilih GET /api/todoitems>Cobalah.
  • Atur bidang id ke 1 dan pilih Jalankan.

• Atau, panggil GET /api/todoitems dari browser dengan memasukkan URI https://localhost:<port>/api/todoitems/1. Misalnya: https://localhost:7260/api/todoitems/1

• Responsnya mirip dengan yang berikut ini:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

Memeriksa metode GET

Dua titik akhir GET diimplementasikan:

• GET /api/todoitems
• GET /api/todoitems/{id}

Bagian sebelumnya menunjukkan contoh rute /api/todoitems/{id}.

Ikuti petunjuk POST untuk menambahkan item todo lain, lalu uji /api/todoitems rute menggunakan Swagger.

Aplikasi ini menggunakan database dalam memori. Jika aplikasi dihentikan dan dimulai, permintaan GET sebelumnya tidak mengembalikan data apa pun. Jika tidak ada data yang dikembalikan, KIRIM data ke aplikasi.

Perutean dan jalur URL

Atribut [HttpGet] menunjukkan metode yang merespons HTTP GET permintaan. Jalur URL untuk setiap metode dibangun sebagai berikut:

• Mulailah dengan string templat di atribut pengontrol Route :

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Ganti [controller] dengan nama pengontrol, yang menurut konvensi adalah nama kelas pengontrol dikurangi akhiran "Pengontrol". Untuk sampel ini, nama kelas pengontrol adalah TodoItemsController, sehingga nama pengontrol adalah "TodoItems". ASP.NET Core routing tidak sensitif terhadap huruf besar/kecil.

• [HttpGet] Jika atribut memiliki templat rute (misalnya, [HttpGet("products")]), tambahkan ke jalur. Sampel ini tidak menggunakan templat. Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Dalam metode berikut GetTodoItem , "{id}" adalah variabel tempat penampung untuk pengidentifikasi unik item yang harus dilakukan. Ketika GetTodoItem dipanggil, nilai "{id}" dalam URL disediakan untuk metode dalam parameternya id .

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Mengembalikan nilai

Jenis pengembalian metode GetTodoItems dan GetTodoItem adalah jenis ActionResult<T>. ASP.NET Core secara otomatis menserialisasikan objek ke JSON dan menulis JSON ke dalam isi pesan respons. Kode respons untuk jenis pengembalian ini adalah 200 OK, dengan asumsi tidak ada pengecualian yang tidak tertangani. Pengecualian yang tidak tertangani diterjemahkan ke dalam kesalahan 5xx.

ActionResult jenis pengembalian dapat mewakili berbagai kode status HTTP. Misalnya, GetTodoItem dapat mengembalikan dua nilai status yang berbeda:

• Jika tidak ada item yang cocok dengan ID yang diminta, metode mengembalikan kode kesalahan statusNotFound 404.
• Jika tidak, metode mengembalikan 200 dengan isi respons JSON. Mengembalikan hasil item dalam respons HTTP 200.

Metode PutTodoItem

Periksa PutTodoItem metode :

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem mirip dengan PostTodoItem, kecuali menggunakan HTTP PUT. Responsnya adalah 204 (Tidak Ada Konten). Menurut spesifikasi HTTP, PUT permintaan mengharuskan klien untuk mengirim seluruh entitas yang diperbarui, bukan hanya perubahan. Untuk mendukung pembaruan parsial, gunakan HTTP PATCH.

Menguji metode PutTodoItem

Sampel ini menggunakan database dalam memori yang harus diinisialisasi setiap kali aplikasi dimulai. Harus ada item dalam database sebelum Anda melakukan panggilan PUT. Panggil GET untuk memastikan ada item dalam database sebelum melakukan panggilan PUT.

Gunakan metode PUT untuk memperbarui TodoItem yang memiliki Id = 1 dan atur namanya ke "feed fish". Perhatikan bahwa responsnya adalah HTTP 204 No Content.

Visual Studio

• Di Endpoints Explorer, klik kanan pada endpoint PUT, dan pilih Generate request.

  Konten berikut ditambahkan ke TodoApi.http file:

  PUT {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

• Di baris permintaan PUT, ganti {{id}} dengan 1.

• Ganti pengganti //TodoItem dengan baris-baris berikut:

  PUT {{TodoApi_HostAddress}}/api/todoitems/1
  Content-Type: application/json
  
  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Pilih tautan Kirim permintaan yang berada di atas baris permintaan PUT baru.

  Permintaan PUT dikirim ke aplikasi dan respons ditampilkan di panel Respons . Isi respons kosong, dan kode status adalah 204.

Visual Studio Code

Gunakan Swagger untuk mengirim permintaan PUT:

• Pilih Put /api/todoitems/{id}>Cobalah.

• Atur bidang id ke 1.

• Atur isi permintaan ke JSON berikut:

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Pilih Jalankan.

Metode DeleteTodoItem

Periksa DeleteTodoItem metode :

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Menguji metode DeleteTodoItem

Gunakan metode DELETE untuk menghapus TodoItem yang memiliki Id = 1. Perhatikan bahwa responsnya adalah HTTP 204 No Content.

Visual Studio

• Di Penjelajah Titik Akhir, klik kanan titik akhir DELETE dan pilih Hasilkan permintaan.

  Permintaan DELETE ditambahkan ke TodoApi.http.

• Ganti {{id}} di baris permintaan DELETE dengan 1. Permintaan DELETE akan terlihat seperti contoh berikut:

  DELETE {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Pilih tautan Kirim permintaan untuk permintaan DELETE.

  Permintaan DELETE dikirim ke aplikasi dan respons ditampilkan di panel Respons . Isi respons kosong, dan kode status adalah 204.

Visual Studio Code

Gunakan Swagger untuk mengirim permintaan DELETE:

• Pilih HAPUS /api/todoitems/{id}>Cobalah.

• Atur bidang ID ke 1 dan pilih Jalankan.

  Permintaan DELETE dikirim ke aplikasi dan respons ditampilkan di panel Respons . Isi respons kosong, dan kode status respons Server adalah 204.

Uji dengan alat lain

Ada banyak alat lain yang dapat digunakan untuk menguji API web, misalnya:

• http-repl
• curl. Swagger menggunakan curl dan menunjukkan perintah curl yang dikirimkan.
• Fiddler

Cegah postingan berlebihan

Saat ini aplikasi sampel mengekspos seluruh TodoItem objek. Aplikasi produksi biasanya membatasi data yang diinput dan dikembalikan menggunakan subset model. Ada beberapa alasan di balik ini, dan keamanan adalah yang utama. Subset model biasanya disebut sebagai Objek Transfer Data (DTO), model input, atau model tampilan. DTO digunakan dalam tutorial ini.

DTO dapat digunakan untuk:

• Cegah postingan berlebihan.
• Sembunyikan properti yang seharusnya tidak dilihat klien.
• Hilangkan beberapa properti untuk mengurangi ukuran payload.
• Meratakan grafik objek yang berisi objek berlapis. Grafik objek yang telah diratakan dapat lebih praktis bagi pengguna.

Untuk menunjukkan pendekatan DTO, perbarui TodoItem kelas untuk menyertakan bidang rahasia:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
    public string? Secret { get; set; }
}

Bidang rahasia perlu disembunyikan dari aplikasi ini, tetapi aplikasi administratif dapat memilih untuk mengeksposnya.

Verifikasi bahwa Anda dapat mengirimkan dan mendapatkan kolom rahasia.

Buat model DTO dalam file Model/TodoItemsDTO.cs :

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Perbarui TodoItemsController untuk menggunakan TodoItemDTO.

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Pastikan bahwa Anda tidak dapat memposting atau mengakses bidang rahasia.

Memanggil API web dengan JavaScript

Lihat Tutorial: Memanggil API web ASP.NET Core dengan JavaScript.

Seri video Web API

Lihat Video: Seri untuk Pemula: API Web.

Pola aplikasi web perusahaan

Untuk panduan tentang membuat aplikasi ASP.NET Core yang andal, aman, berkinerja, dapat diuji, dan dapat diskalakan, lihat Pola aplikasi web perusahaan. Contoh aplikasi web dengan kualitas produksi lengkap yang menerapkan pola-pola tersedia.

Menambahkan dukungan autentikasi ke API web

ASP.NET Core Identity menambahkan fungsionalitas masuk antarmuka pengguna (UI) ke aplikasi web ASP.NET Core. Untuk mengamankan API web dan SPAs, gunakan salah satu hal berikut ini:

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Server

Duende Identity Server adalah kerangka kerja OpenID Connect dan OAuth 2.0 untuk ASP.NET Core. Duende Identity Server memungkinkan fitur keamanan berikut:

• Autentikasi sebagai Layanan (AaaS)
• Sistem masuk/keluar tunggal (SSO) untuk beberapa jenis aplikasi
• Kontrol akses untuk API
• Gateway Federasi

Important

Perangkat Lunak Duende mungkin mengharuskan Anda membayar biaya lisensi untuk penggunaan produksi Server Identity Duende. Untuk informasi selengkapnya, lihat Migrasi dari ASP.NET Core di .NET 5 ke .NET 6.

Untuk informasi selengkapnya, lihat dokumentasi Duende Identity Server (situs web Duende Software).

Menerbitkan ke Azure

Untuk informasi tentang penyebaran ke Azure, lihat Mulai Cepat: Menyebarkan aplikasi web ASP.NET.

Sumber daya tambahan

Lihat atau unduh kode sampel untuk tutorial ini. Lihat cara mengunduh.

Untuk informasi selengkapnya, lihat sumber daya berikut:

• Membuat API web dengan ASP.NET Core
• Tutorial: Membuat API minimal dengan ASP.NET Core
• Menggunakan dokumen OpenAPI yang dihasilkan
• dokumentasi API web ASP.NET Core dengan Swagger / OpenAPI
• Razor Halaman dengan Entity Framework Core di ASP.NET Core - Tutorial 1 dari 8
• Pengaturan rute ke aksi pengontrol di ASP.NET Core
• Jenis pengembalian tindakan pengontrol di API web ASP.NET Core
• Menyebarkan aplikasi ASP.NET Core ke Azure App Service
• Menampung dan sebarkan ASP.NET Core
• Membuat API web dengan ASP.NET Core