Phần lớn API “REST” trong các dự án .NET không thất bại vì thiếu endpoint, mà vì sai ngữ nghĩa: dùng POST cho mọi thứ, trả 200 kèm { "success": false }, trả 403 khi người dùng chưa đăng nhập, và phân trang bằng offset trên một bảng đang thay đổi liên tục. Những lỗi này không làm app crash, nhưng làm client khó đoán, cache vô dụng và incident khó điều tra.
Bài này là bản cập nhật 2026 của chặng REST trong lộ trình .NET: thiết kế tài nguyên, dùng đúng method và status code, chuẩn hóa lỗi bằng ProblemDetails, phân trang bằng cursor, versioning, và những gì ASP.NET Core 10 làm sẵn để bạn không phải tự viết lại.
Mục lục
Cập nhật 2026: ba thứ thay đổi cách viết REST API
- OpenAPI 3.1 là mặc định.
Microsoft.AspNetCore.OpenApisinh tài liệu trực tiếp từ endpoint; Swashbuckle không còn là lựa chọn mặc định. OpenAPI 3.1 dùng JSON Schema 2020-12, nên kiểu nullable được biểu diễn bằng mảngtype: ["string","null"]thay vìnullable: true. - Validation tích hợp cho Minimal APIs.
builder.Services.AddValidation()bật kiểm tra DataAnnotations trên query, header và body; lỗi trả về tự động dưới dạngValidationProblemDetailsvới 400. Bạn không cần tự viết một middleware validate cho từng endpoint. - ProblemDetails là chuẩn lỗi, không phải tùy chọn. RFC 9457 (bản thay thế RFC 7807) đã được .NET hỗ trợ qua
TypedResults.Problem/ValidationProblem. Client có thể xử lý lỗi theo một cấu trúc thống nhất.
1. Thiết kế tài nguyên trước, endpoint sau
REST không phải “gọi hàm qua HTTP”. Nó là mô hình tài nguyên: mỗi URL đại diện cho một thứ có thể định danh, và method mô tả hành động trên thứ đó. Trước khi viết MapPost, hãy trả lời ba câu:
- Tài nguyên là gì? (
/orders,/orders/{id},/orders/{id}/items) - Ai sở hữu nó? (tenant, user, organization — thường nên nằm trong route hoặc token, không nằm trong body)
- Nó thay đổi theo mô hình nào? (tạo, cập nhật toàn phần, cập nhật một phần, chuyển trạng thái)
Quy tắc thực dụng: danh từ số nhiều cho collection, ID trong path cho một item, tối đa hai cấp lồng nhau. /customers/42/orders hợp lý; /customers/42/orders/7/items/3/refunds là dấu hiệu nên tách tài nguyên hoặc dùng query parameter. Các hành động không phải CRUD (gửi, hủy, phê duyệt) có thể dùng sub-resource hoặc động từ có kiểm soát: POST /orders/42/cancel dễ hiểu hơn PATCH /orders/42 với body {"status":"cancelled"} khi việc hủy có side effect (hoàn tiền, gửi mail).
2. Method và tính idempotent
| Method | Dùng cho | Idempotent? |
|---|---|---|
GET |
Đọc, không thay đổi trạng thái | Có |
POST |
Tạo mới, hành động có side effect | Không (trừ khi có idempotency key) |
PUT |
Thay thế toàn bộ tài nguyên | Có |
PATCH |
Cập nhật một phần | Không nhất thiết |
DELETE |
Xóa | Có (xóa lần hai vẫn là “đã xóa”) |
Điểm dễ sai nhất là PUT “một phần”. Nếu client gửi thiếu field, PUT phải hiểu là “đặt toàn bộ tài nguyên về giá trị này”, thường dẫn đến xóa dữ liệu ngoài ý muốn. Muốn cập nhật một phần, dùng PATCH với JSON Merge Patch (application/merge-patch+json) hoặc JSON Patch (application/json-patch+json). .NET 10 có implementation JSON Patch dựa trên System.Text.Json, nhẹ hơn bản cũ dùng Newtonsoft.
POST tạo đơn hàng/thanh toán là nơi idempotency thực sự quan trọng. Client retry sau timeout có thể tạo hai đơn. Cách xử lý đúng: yêu cầu header Idempotency-Key, lưu key + kết quả trong Redis/DB với TTL, và trả lại response cũ nếu key đã được xử lý. Đây là bài toán nghiệp vụ, không phải middleware chung có thể giải quyết cho mọi endpoint.
3. Status code: trả đúng để client không phải đoán
| Tình huống | Code | Ghi chú |
|---|---|---|
| Tạo thành công | 201 Created |
Kèm Location trỏ tới tài nguyên mới |
| Đọc/cập nhật thành công, có body | 200 OK |
|
| Xóa thành công, không body | 204 No Content |
|
| Request sai định dạng/thiếu field | 400 Bad Request |
Validation lỗi dùng ValidationProblemDetails |
| Chưa xác thực | 401 Unauthorized |
Kèm WWW-Authenticate |
| Đã xác thực nhưng không có quyền | 403 Forbidden |
Không tiết lộ tài nguyên có tồn tại hay không nếu cần giấu |
| Không tìm thấy | 404 Not Found |
|
| Xung đột trạng thái/unique | 409 Conflict |
Ví dụ tạo trùng email |
| Vi phạm precondition (ETag) | 412 Precondition Failed |
Optimistic concurrency |
| Đã hiểu nhưng không xử lý được về mặt ngữ nghĩa | 422 Unprocessable Content |
Không bắt buộc nếu bạn đã dùng 400 + ProblemDetails |
| Quá nhiều request | 429 Too Many Requests |
Kèm Retry-After |
| Server quá tải | 503 Service Unavailable |
Hai lỗi phổ biến: trả 403 khi chưa đăng nhập (phải là 401), và trả 200 với body lỗi. Lỗi thứ hai làm SDK, proxy, cache và monitoring đều hiểu sai. Nếu cần tương thích với client cũ, hãy giữ endpoint cũ nhưng đặt deprecation rõ ràng, đừng tiếp tục trả 200 cho lỗi.
4. DTO, validation và error contract
Đừng trả entity EF Core trực tiếp. Entity có navigation property, cột nội bộ và vòng lặp tham chiếu; DTO là hợp đồng công khai, cho phép đổi schema DB mà không phá client. Dùng record + required/init để ý định rõ ràng:
// File: Contracts/CreateOrderRequest.cs
public sealed record CreateOrderRequest(
[property: Required, MinLength(1)] string CustomerName,
[property: Range(1, 100)] int Quantity,
[property: EmailAddress] string? ContactEmail);
Với ASP.NET Core 10, bật validation một lần:
builder.Services.AddValidation();
Lỗi validation tự động đi qua ProblemDetails. Nếu cần thông báo nghiệp vụ riêng, dùng FluentValidation 12 hoặc validate trong handler và trả TypedResults.ValidationProblem với key trùng tên field:
app.MapPost("/orders", async (CreateOrderRequest request, OrderService service, CancellationToken ct) =>
{
if (request.Quantity > 100)
{
return Results.ValidationProblem(new Dictionary<string, string[]>
{
["quantity"] = ["Số lượng tối đa là 100."]
});
}
var order = await service.CreateAsync(request, ct);
return TypedResults.Created($"/orders/{order.Id}", order.ToDto());
})
.WithName("CreateOrder")
.ProducesProblem(StatusCodes.Status400BadRequest);
Với lỗi hệ thống, hãy trả ProblemDetails có type, title, status, detail và traceId. Đừng trả stack trace hay message của exception ra ngoài. Trong .NET 10, exception handler mặc định không ghi log các exception đã được IExceptionHandler xử lý; nếu bạn muốn log lại, cấu hình SuppressDiagnosticsCallback thay vì tự viết middleware.
5. Phân trang, lọc, sắp xếp
Offset pagination (?page=3&pageSize=20) dễ viết nhưng sai khi dữ liệu thay đổi: item có thể bị lặp hoặc bị bỏ qua giữa hai trang. Với feed, log, giao dịch, hãy dùng cursor:
GET /orders?cursor=eyJjcmVhdGVkQXQiOiIyMDI2LTExLTA3VDEwOjAwOjAwWiIsImlkIjo0Mn0&limit=50
Cursor nên là opaque (base64 của createdAt + id), không phải ID trần — ID trần dễ bị đoán và không đảm bảo thứ tự. Luôn giới hạn limit tối đa (ví dụ 100) và trả về nextCursor. Với bộ lọc, whitelist field được phép lọc; đừng nhận tên cột SQL từ query string.
Sắp xếp phải có tie-breaker (createdAt DESC, id DESC) để thứ tự ổn định. Nếu không, hai bản ghi cùng thời điểm có thể đổi chỗ giữa các lần gọi và cursor bị nhảy.
6. Versioning và deprecation
Ba cách phổ biến: URL (/v1/orders), header (api-version: 1.0), media type. URL versioning dễ debug và dễ route nhất; header versioning sạch hơn về mặt REST nhưng khó thấy trong log. Dù chọn cách nào, hãy viết policy: version nào còn hỗ trợ, thời hạn deprecation, và trả header Deprecation/Sunset (RFC 8594) thay vì chỉ ghi trong tài liệu.
Đừng version vì thêm field mới. Thêm field optional là thay đổi tương thích; chỉ lên version khi thay đổi ngữ nghĩa hoặc xóa field. Client cũ thường bỏ qua field lạ, nhưng không bỏ qua field bị đổi kiểu.
7. Bảo mật và vận hành
- Auth: JWT bearer hoặc cookie; phân quyền theo resource, không chỉ theo role. Kiểm tra tenant ở mọi query, không tin
tenantIdtừ body. - Rate limiting:
AddRateLimiterlà middleware sẵn có. Mặc định trả 503 khi vượt hạn mức; đặtRejectionStatusCode = 429nếu bạn muốn đúng ngữ nghĩa HTTP hơn. - Output caching/ETag: endpoint đọc nhiều, ít thay đổi nên có
ETagvà304. Với dữ liệu theo user, dùngCache-Control: privatevàVaryđúng header. - CORS: chỉ mở origin cần thiết; credential + wildcard origin không hợp lệ.
- Observability: log theo
traceId, đo p95/p99, đếm 4xx/5xx theo endpoint. OpenAPI không thay thế monitoring.
8. Ví dụ cấu trúc một endpoint đủ tốt
// File: Program.cs (Minimal API, .NET 10)
builder.Services.AddValidation();
builder.Services.AddOpenApi();
builder.Services.AddProblemDetails();
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/orders/{id:int}", async (int id, OrderService service, CancellationToken ct) =>
{
var order = await service.FindAsync(id, ct);
return order is null
? Results.Problem(statusCode: StatusCodes.Status404NotFound, title: "Order not found")
: Results.Ok(order.ToDto());
})
.WithName("GetOrder")
.Produces<OrderDto>(StatusCodes.Status200OK)
.ProducesProblem(StatusCodes.Status404NotFound);
Điểm quan trọng không nằm ở cú pháp mà ở hợp đồng: endpoint có tên, có kiểu trả về, có tài liệu lỗi, và có CancellationToken xuyên suốt. Những thứ nhỏ này quyết định API có dễ bảo trì sau 12 tháng hay không.
9. Idempotency key: cách làm đúng
Đừng chỉ kiểm tra “key đã tồn tại chưa” rồi trả 200. Làm vậy, hai request đồng thời có thể cùng thấy key chưa tồn tại và cùng tạo đơn. Cần ba trạng thái: in-flight, completed, và failed.
- Request đầu tiên ghi key với trạng thái
in-flightbằngSET NX(Redis) hoặc unique index (DB), TTL ngắn (ví dụ 60 giây). - Các request đồng thời gặp
in-flightnhận409 ConflictkèmRetry-After, không được xử lý nghiệp vụ. - Khi xử lý xong, lưu status code + body + header quan trọng vào key với TTL dài hơn (24 giờ). Request retry nhận lại đúng response cũ.
- Nếu xử lý thất bại, đổi trạng thái để client có thể thử lại — hoặc giữ nguyên nếu lỗi là vĩnh viễn (ví dụ validation).
Key phải gắn với user/tenant và endpoint, không chỉ là chuỗi client gửi lên. Nếu không, một client có thể dùng key của tenant khác và nhận response không thuộc về mình.
10. Content negotiation và PATCH
Đừng hard-code application/json ở mọi nơi. Hãy để client thương lượng qua Accept, và trả 406 Not Acceptable nếu không hỗ trợ. Với PATCH, chọn một trong hai chuẩn và ghi rõ trong tài liệu:
- JSON Merge Patch (
application/merge-patch+json): body là object chứa các field muốn đổi; fieldnullnghĩa là xóa. Đơn giản nhưng không diễn tả được thao tác trên mảng. - JSON Patch (
application/json-patch+json): body là danh sách operationadd/replace/remove/move/copy/test. Mạnh hơn, phù hợp khi cần sửa phần tử trong mảng hoặc kiểm tra precondition bằngtest.
Đừng nhận PATCH dạng “object tùy ý” rồi tự suy luận field nào được phép đổi. Whitelist field theo từng loại tài nguyên và từng role; nếu không, client có thể đổi status, ownerId hoặc field nội bộ mà bạn không định mở.
Checklist trước khi release
- Mỗi endpoint có resource rõ ràng, method đúng, status code đúng.
- Không trả entity; DTO có validation và không nhận field ngoài whitelist.
- Lỗi trả ProblemDetails, không lộ stack trace.
- Collection có giới hạn page size và cursor/tie-breaker ổn định.
- POST tạo tài nguyên quan trọng có idempotency key.
- OpenAPI 3.1 được sinh và được review như một phần của API contract.
- Rate limiting, auth, tenant check, log traceId đều có.
Bước tiếp theo trong lộ trình: nếu API của bạn cần client tự chọn field và giảm round-trip, đọc bài GraphQL với HotChocolate; nếu cần contract chặt và hiệu năng cao giữa các service nội bộ, đọc bài gRPC; nếu cần client tự truy vấn linh hoạt trên dữ liệu có sẵn, đọc bài OData — nhưng hãy đọc phần bảo mật trước khi bật nó lên production.
Xem lại nền tảng HTTP/HTTPS nếu bạn chưa chắc về cache header, 401/403 hay CORS. Và nếu API đọc nhiều, đừng bỏ qua bài chiến lược cache — phần lớn cải thiện hiệu năng REST đến từ cache đúng chỗ, không phải từ micro-optimization trong handler.



