Nguon: Microsoft Learn · .NET 8.0

Tổng quan về API (APIs overview)

Nguồn: ASP.NET Core API overview | Phiên bản: .NET 8.0

Trong bài viết này

Đây không phải phiên bản mới nhất của bài viết này. Để xem phiên bản hiện tại, hãy tham khảo bài viết phiên bản .NET 10.

Phiên bản ASP.NET Core này không còn được hỗ trợ nữa. Để biết thêm thông tin, xem Chính sách hỗ trợ .NET và .NET Core. Để xem phiên bản hiện tại, hãy tham khảo bài viết phiên bản .NET 10.

ASP.NET Core cung cấp hai cách tiếp cận để xây dựng HTTP API (giao diện lập trình ứng dụng HTTP): Minimal API và Controller-based API (API dựa trên Controller). Đối với các dự án mới, chúng tôi khuyến nghị sử dụng Minimal API vì chúng cung cấp cách tiếp cận đơn giản, hiệu suất cao để xây dựng API với ít code và cấu hình nhất.

Minimal API - Khuyến nghị cho các dự án mới

Minimal API là cách tiếp cận được khuyến nghị để xây dựng HTTP API nhanh với ASP.NET Core. Chúng cho phép bạn xây dựng các REST Endpoint (điểm cuối REST) đầy đủ chức năng với lượng code và cấu hình tối thiểu. Bỏ qua scaffolding (tạo khung) truyền thống và tránh các Controller không cần thiết bằng cách khai báo linh hoạt các route (tuyến đường) và action (hành động) của API.

Dưới đây là một ví dụ đơn giản tạo một API tại gốc của ứng dụng web:

csharp
var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

Hầu hết các API nhận tham số (parameter) như một phần của route:

csharp
var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/users/{userId}/books/{bookId}",
    (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");

app.Run();

Minimal API hỗ trợ cấu hình và tùy chỉnh cần thiết để mở rộng quy mô với nhiều API, xử lý các route phức tạp, áp dụng các quy tắc authorization (phân quyền), và kiểm soát nội dung response (phản hồi) của API.

Bắt đầu với Minimal API

Controller-based API - Cách tiếp cận thay thế

ASP.NET Core cũng hỗ trợ cách tiếp cận dựa trên Controller, trong đó các Controller là các class (lớp) kế thừa từ ControllerBase. Cách tiếp cận này tuân theo các mẫu hướng đối tượng truyền thống và có thể được ưu tiên khi:

Dưới đây là code mẫu cho một API dựa trên Controller:

csharp
namespace APIWithControllers;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers();
        var app = builder.Build();

        app.UseHttpsRedirection();

        app.MapControllers();

        app.Run();
    }
}
csharp
using Microsoft.AspNetCore.Mvc;

namespace APIWithControllers.Controllers;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

Đoạn code sau cung cấp chức năng tương tự sử dụng cách tiếp cận Minimal API được khuyến nghị:

csharp
namespace MinimalAPI;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        var app = builder.Build();

        app.UseHttpsRedirection();

        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        app.MapGet("/weatherforecast", (HttpContext httpContext) =>
        {
            var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                {
                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    TemperatureC = Random.Shared.Next(-20, 55),
                    Summary = summaries[Random.Shared.Next(summaries.Length)]
                })
                .ToArray();
            return forecast;
        });

        app.Run();
    }
}

Cả hai dự án API đều tham chiếu đến class sau:

csharp
namespace APIWithControllers;

public class WeatherForecast
{
    public DateOnly Date { get; set; }

    public int TemperatureC { get; set; }

    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

    public string? Summary { get; set; }
}

Lựa chọn giữa các cách tiếp cận

Bắt đầu với Minimal API cho các dự án mới. Chúng cung cấp:

Cân nhắc sử dụng Controller-based API nếu bạn cần:

Hầu hết các tính năng này có thể được triển khai trong Minimal API bằng các giải pháp tùy chỉnh, nhưng Controller cung cấp chúng sẵn có (out of the box).

Xem thêm