Membuat project ASP.NET Core Web API pertama adalah langkah awal untuk membangun backend yang bisa diakses oleh aplikasi client, baik itu aplikasi mobile, single-page application, maupun layanan lain yang berkomunikasi lewat HTTP menggunakan format data seperti JSON.

Dotnet CLI menyediakan template webapi yang langsung menghasilkan struktur project lengkap dengan controller contoh, konfigurasi Swagger untuk dokumentasi API otomatis, dan pengaturan dasar yang siap dijalankan tanpa konfigurasi tambahan.

Artikel ini membahas langkah demi langkah membuat project Web API baru, memahami struktur file yang dihasilkan, serta cara menguji endpoint API tersebut menggunakan Swagger UI yang disediakan secara otomatis.

Membuat Project dengan Template webapi

Template webapi langsung menghasilkan project siap jalan

dotnet new webapi -n TokoOnlineApi cd TokoOnlineApi dotnet run -- Expected: aplikasi berjalan di https://localhost:5001 -- dengan Swagger UI otomatis tersedia di /swagger
Perintah dotnet new webapi menghasilkan project lengkap dengan file Program.cs yang sudah dikonfigurasi dasar, controller contoh WeatherForecastController, serta Swagger yang otomatis aktif pada mode development untuk mendokumentasikan dan menguji endpoint API secara interaktif langsung dari browser.

Memahami Controller dan Action Method

Controller dasar dengan satu endpoint GET

[ApiController] [Route("api/[controller]")] public class ProdukController : ControllerBase { [HttpGet] public IActionResult GetSemua() { var produk = new List<string> { "Laptop", "Mouse", "Keyboard" }; return Ok(produk); } }
Atribut [ApiController] mengaktifkan berbagai konvensi otomatis seperti validasi model binding, sementara [Route] mendefinisikan pola URL yang akan memetakan ke controller tersebut. Method GetSemua yang ditandai [HttpGet] akan merespons request GET ke endpoint /api/Produk, mengembalikan data dalam format JSON secara otomatis lewat Ok().

Menguji API dengan Swagger UI

Swagger UI memberi cara cepat menguji API tanpa tool tambahan

// Swagger otomatis membaca atribut controller // dan menghasilkan dokumentasi interaktif di /swagger // Developer bisa langsung mencoba endpoint // tanpa perlu tool eksternal seperti Postman
Swagger (OpenAPI) secara otomatis membaca struktur controller dan menghasilkan halaman dokumentasi interaktif yang memungkinkan developer mencoba setiap endpoint langsung dari browser, melihat parameter yang dibutuhkan, dan memeriksa response yang dihasilkan, sangat membantu selama tahap development sebelum API tersebut dipakai oleh aplikasi client sungguhan.

Menjalankan dengan Hot Reload untuk Produktivitas

dotnet watch mempercepat siklus development

dotnet watch run -- Expected: perubahan kode otomatis ter-compile ulang -- dan aplikasi restart tanpa perlu menghentikan dan -- menjalankan ulang dotnet run secara manual
Perintah dotnet watch run memantau perubahan file kode secara otomatis dan langsung mengompilasi ulang serta me-restart aplikasi begitu ada perubahan disimpan, menghilangkan kebutuhan menghentikan dan menjalankan ulang aplikasi secara manual setiap kali melakukan perubahan kecil selama development.

Selain template webapi standar, dotnet CLI juga menyediakan flag tambahan seperti --use-controllers atau --minimal untuk memilih gaya minimal API tanpa controller class, sebuah pendekatan yang semakin populer pada project kecil hingga menengah karena mengurangi boilerplate sekaligus tetap mempertahankan seluruh kemampuan routing dan dependency injection yang sama.

Memahami appsettings dan launchSettings pada Project Baru

launchSettings.json menentukan port dan environment saat debug di Visual Studio/dotnet run

// launchSettings.json (Properties folder) - hanya dipakai saat development lokal { "profiles": { "WeatherApi": { "commandName": "Project", "applicationUrl": "https://localhost:7101;http://localhost:5101", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" } } } } // File ini TIDAK ikut ter-deploy ke server production.

Ketika project ASP.NET Core Web API baru dibuat lewat template bawaan, dua file konfigurasi langsung tersedia: appsettings.json dan launchSettings.json. Keduanya sering tertukar fungsinya oleh pemula. appsettings.json berisi konfigurasi aplikasi yang dibaca saat runtime dan ikut dideploy ke server, sedangkan launchSettings.json hanya dipakai oleh tooling development (Visual Studio, dotnet run, Rider) untuk menentukan port lokal dan variabel environment saat debugging, dan tidak pernah ikut masuk ke hasil publish.

Variabel ASPNETCORE_ENVIRONMENT yang didefinisikan di launchSettings.json itulah yang menentukan file konfigurasi mana yang akan digabung saat aplikasi start, misalnya appsettings.Development.json akan menimpa nilai di appsettings.json dasar ketika environment bernilai Development. Di server production, nilai ini biasanya diset lewat environment variable sistem operasi atau konfigurasi hosting, bukan lewat launchSettings.json yang memang tidak pernah sampai ke server.

Memahami urutan pemuatan konfigurasi ini penting sejak project pertama kali dibuat, karena kesalahan umum pemula adalah menaruh connection string production langsung di appsettings.json lalu bingung mengapa nilai tersebut masih terpakai di server padahal sudah ada appsettings.Production.json; urutan override konfigurasi di ASP.NET Core berjalan dari file paling umum ke file paling spesifik sesuai environment.

Menambahkan Swagger/OpenAPI untuk Dokumentasi dan Uji Coba API

Swagger UI aktif hanya pada environment Development

// Program.cs - mendaftarkan Swagger/OpenAPI var builder = WebApplication.CreateBuilder(args); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(opt => { opt.SwaggerDoc("v1", new() { Title = "WeatherApi", Version = "v1" }); }); var app = builder.Build(); if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); // tersedia di /swagger } app.MapControllers(); app.Run(); // Buka https://localhost:7101/swagger untuk mencoba endpoint langsung dari browser

Project Web API baru yang dibuat lewat template dotnet new webapi biasanya sudah menyertakan package Swashbuckle.AspNetCore secara otomatis, yang menghasilkan dokumentasi OpenAPI dari seluruh controller dan DTO yang ada di project. Dokumentasi ini dibaca langsung dari signature method, atribut [HttpGet]/[HttpPost], dan tipe parameter, sehingga tidak perlu menulis dokumentasi API secara manual yang mudah basi ketika kode berubah. Skema JSON yang dihasilkan di endpoint /swagger/v1/swagger.json juga bisa langsung diimpor ke tools eksternal seperti Postman atau dipakai untuk membangkitkan client SDK secara otomatis di sisi frontend.

Swagger UI yang muncul di endpoint /swagger memberi antarmuka interaktif untuk mencoba setiap endpoint langsung dari browser tanpa perlu Postman, termasuk mengisi body request, melihat skema response, dan menguji endpoint yang membutuhkan header Authorization. Fitur Try it out ini sangat membantu saat tahap pengembangan awal karena developer bisa langsung memverifikasi perilaku API begitu controller baru dibuat. Komentar XML pada method controller, jika diaktifkan lewat GenerateDocumentationFile di csproj, juga akan muncul sebagai deskripsi tambahan di halaman Swagger tanpa konfigurasi lain.

Praktik umum adalah membatasi UseSwaggerUI() hanya aktif pada environment Development lewat pengecekan app.Environment.IsDevelopment(), karena mengekspos dokumentasi API lengkap beserta skema data di production berisiko membocorkan detail struktur internal sistem ke pihak yang tidak berkepentingan. Untuk API yang memang perlu didokumentasikan secara publik, biasanya dipakai domain atau subdomain terpisah dengan autentikasi tambahan, bukan endpoint swagger bawaan yang sama dengan environment development. Tim yang tetap membutuhkan swagger di production umumnya menambahkan proteksi tambahan seperti basic authentication khusus pada path tersebut.

Menambahkan API Versioning agar Perubahan Kontrak Tidak Merusak Klien Lama

builder.Services.AddApiVersioning(options => { options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; options.ReportApiVersions = true; }); [ApiVersion("1.0")] [Route("api/v{version:apiVersion}/produk")] public class ProdukController : ControllerBase { } // Klien lama tetap memanggil /api/v1/produk walau v2 sudah dirilis

Pada project baru yang masih kecil, versioning sering dianggap belum perlu karena hanya ada satu klien yang memanggil API tersebut. Namun begitu API mulai dikonsumsi oleh lebih dari satu pihak, misalnya aplikasi mobile, aplikasi web internal, dan sistem partner sekaligus, perubahan kontrak endpoint bisa berisiko mematahkan klien yang belum sempat diperbarui mengikuti perubahan terbaru. Library resmi Asp.Versioning menyediakan skema versi lewat segmen URL, query string, atau header kustom tanpa harus menulis logika routing manual untuk membedakan setiap versi secara terpisah.

ReportApiVersions berguna untuk menampilkan versi yang didukung lewat response header, sehingga tim konsumen API dapat memeriksa versi mana saja yang masih aktif dan mana yang sudah mulai ditinggalkan. Menambahkan skema versioning sejak awal, meski baru ada satu versi yang tersedia, jauh lebih mudah dibanding memasangnya belakangan setelah banyak controller sudah terlanjur dibuat tanpa mengikuti pola penomoran versi, yang akan memaksa refactor route di banyak tempat sekaligus.

Kesalahan Umum yang Sering Terjadi

Lupa Menambahkan Atribut HttpGet/HttpPost pada Action Method

Action method yang tidak ditandai atribut HTTP verb yang sesuai bisa menyebabkan konflik routing atau method tersebut tidak bisa diakses sesuai ekspektasi, terutama jika controller memiliki beberapa method dengan nama mirip.

Mengabaikan Swagger Hanya Aktif di Mode Development

Swagger UI secara default hanya aktif saat aplikasi berjalan dalam environment Development; banyak developer bingung mengapa /swagger menghasilkan 404 setelah deploy ke production karena environment-nya sudah berubah.

Tidak Memahami Perbedaan ControllerBase dan Controller

Untuk Web API murni tanpa view, sebaiknya mewarisi dari ControllerBase, bukan Controller yang menyertakan fitur tambahan untuk rendering view MVC yang tidak dibutuhkan pada API.

Kapan Pendekatan Ini Tidak Cocok Dipakai

Template webapi bawaan memberikan starting point yang cepat dengan konfigurasi dasar yang masuk akal, namun untuk project production yang lebih kompleks, struktur ini biasanya perlu disesuaikan lebih lanjut dengan pola arsitektur seperti Clean Architecture yang akan dibahas pada artikel terpisah.

Swagger memberikan kemudahan dokumentasi dan pengujian otomatis tanpa effort tambahan, namun untuk API yang benar-benar kompleks dengan banyak skenario autentikasi, terkadang masih perlu dilengkapi dengan tool pengujian API eksternal seperti Postman untuk skenario yang lebih rumit.

Ringkasan

Membuat project ASP.NET Core Web API pertama relatif cepat berkat template bawaan dotnet CLI yang sudah menyertakan Swagger untuk dokumentasi interaktif. Pahami peran controller, action method, dan atribut routing sebagai fondasi sebelum melangkah ke topik lebih lanjut seperti middleware dan dependency injection.