صفحة تستدعي API
جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 18 من 20.
تشارك الصفحة التي تقدمها واجهة API نفسها الأصل، لذلك لا تحتاج استدعاءات fetch فيها إلى CORS. تتولى برمجيتان وسيطتان تقديم الملفات الموجودة في مجلد wwwroot ضمن المشروع: تحوّل app.UseDefaultFiles() الطلب على / إلى /index.html، وترسل app.UseStaticFiles() الملف. يجب أن تأتي إعادة الكتابة أولًا.
const response = await fetch('/api/products');
const products = await response.json();
for (const product of products) {
const item = document.createElement('li');
item.textContent = product.name;
list.append(item);
}ترسل fetch طلبًا وتُعيد وعدًا بالاستجابة، وتقرأ response.json() محتوى الاستجابة بتنسيق JSON. ينتقل المسار الذي يبدأ بـ / إلى أصل الصفحة نفسها. يعرض textContent الاسم كنص عادي، لذلك لا يمكن لمنتج اسمه <script> أن يعمل كتعليمة برمجية.
التحدي
متوسطأنشئ صفحةً لمتعقّب المهام تعرض قائمة بالمهام. لديك ملف جديد، wwwroot/index.html، يحتوي على عنوان وقائمة <ul id="tasks"> فارغة.
- في
Program.cs، بعدapp.UseCors("board");، أضفapp.UseDefaultFiles();ثمapp.UseStaticFiles(); - في
wwwroot/index.html، في الموضع الذي يشير إليه التعليق، اكتبasync function loadTasks()تجلب/api/tasks، وتقرأ JSON، وتضيف عنصر<li>لكل مهمة إلى القائمة، بحيث يكون عنوان المهمة هوtextContentالخاص به. امنح عنصر المهمة المنجزة الصنفdone، الذي يشطبه نمط الصفحة. ثم استدعِloadTasks().
تُشغّل عمليات التحقق .NET، وليس متصفحًا: فهي تتحقق من أن GET / يعرض الصفحة وأن واجهة API التي تقرؤها لا تزال تعمل. أما القائمة نفسها فتحقق منها في العمود.
جرّب ذلك: اضغط على «تشغيل». يرسل العمود GET / ويعرض الصفحة، التي تسرد المهام الثلاث مع شطب "Book the meeting room". أرسل GET /index.html: الصفحة نفسها. أرسل { "title": "Order new chairs" } باستخدام POST إلى /api/tasks، ثم أرسل GET / مجددًا: ستظهر أربع مهام.
جرّب بنفسك
using System.ComponentModel.DataAnnotations;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
builder.Services.AddCors(options =>
{
options.AddPolicy("board", policy => policy
.WithOrigins("https://board.example.com")
.WithMethods("GET", "POST", "PUT", "PATCH", "DELETE")
.WithHeaders("Content-Type")
.WithExposedHeaders("X-Total-Count"));
});
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseCors("board");
var tasks = new List<TaskItem>
{
new(1, "Write the project brief", false, 1),
new(2, "Book the meeting room", true, 3),
new(3, "Send the invoice", false),
};
var nextId = 4;
bool TitleTaken(string title, int exceptId) =>
tasks.Any(t => t.Id != exceptId && string.Equals(t.Title, title, StringComparison.OrdinalIgnoreCase));
app.MapGet("/api/tasks", (bool? done, string? search, int? priority, string? sort, HttpResponse response, int page = 1, int pageSize = 10) =>
{
var errors = new Dictionary<string, string[]>();
if (sort is not null && sort != "id" && sort != "title" && sort != "priority")
errors["sort"] = ["Sort by id, title or priority."];
if (priority is < 1 or > 3)
errors["priority"] = ["Priority is 1 to 3."];
if (page < 1)
errors["page"] = ["Page starts at 1."];
if (pageSize < 1 || pageSize > 50)
errors["pageSize"] = ["Page size is 1 to 50."];
if (errors.Count > 0) return Results.ValidationProblem(errors);
IEnumerable<TaskItem> result = tasks;
if (done is not null) result = result.Where(t => t.Done == done);
if (!string.IsNullOrWhiteSpace(search))
result = result.Where(t => t.Title.Contains(search, StringComparison.OrdinalIgnoreCase));
if (priority is not null) result = result.Where(t => t.Priority == priority);
if (sort == "title") result = result.OrderBy(t => t.Title);
if (sort == "priority") result = result.OrderBy(t => t.Priority);
var matching = result.ToList();
response.Headers["X-Total-Count"] = matching.Count.ToString();
return Results.Ok(matching.Skip((page - 1) * pageSize).Take(pageSize));
});
app.MapGet("/api/tasks/{id:int}", (int id) =>
{
var task = tasks.Find(t => t.Id == id);
return task is null ? Results.NotFound() : Results.Ok(task);
});
app.MapPost("/api/tasks", (TaskInput input) =>
{
var errors = Validation.Errors(input);
if (errors is not null) return Results.ValidationProblem(errors);
if (TitleTaken(input.Title, 0))
return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
var task = new TaskItem(nextId++, input.Title, input.Done, input.Priority);
tasks.Add(task);
return Results.Created($"/api/tasks/{task.Id}", task);
});
app.MapPut("/api/tasks/{id:int}", (int id, TaskInput input) =>
{
var errors = Validation.Errors(input);
if (errors is not null) return Results.ValidationProblem(errors);
var index = tasks.FindIndex(t => t.Id == id);
if (index == -1) return Results.NotFound();
if (TitleTaken(input.Title, id))
return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
tasks[index] = new TaskItem(id, input.Title, input.Done, input.Priority);
return Results.Ok(tasks[index]);
});
app.MapPatch("/api/tasks/{id:int}", (int id, TaskPatch patch) =>
{
var errors = Validation.Errors(patch);
if (errors is not null) return Results.ValidationProblem(errors);
var index = tasks.FindIndex(t => t.Id == id);
if (index == -1) return Results.NotFound();
if (patch.Title is not null && TitleTaken(patch.Title, id))
return Results.Problem(title: "A task with this title already exists.", statusCode: 409);
var task = tasks[index];
tasks[index] = task with
{
Title = patch.Title ?? task.Title,
Done = patch.Done ?? task.Done,
Priority = patch.Priority ?? task.Priority,
};
return Results.Ok(tasks[index]);
});
app.MapDelete("/api/tasks/{id:int}", (int id) =>
{
var removed = tasks.RemoveAll(t => t.Id == id);
return removed == 0 ? Results.NotFound() : Results.NoContent();
});
app.MapDelete("/api/tasks", (bool? done) =>
{
if (done != true)
{
return Results.ValidationProblem(new Dictionary<string, string[]>
{
["done"] = ["Add ?done=true to delete the done tasks."],
});
}
tasks.RemoveAll(t => t.Done);
return Results.NoContent();
});
app.Run();
record TaskItem(int Id, string Title, bool Done, int Priority = 2);
record TaskInput(
[property: Required(ErrorMessage = "Title is required."), StringLength(80)] string Title,
bool Done,
[property: Range(1, 3)] int Priority = 2);
record TaskPatch(string? Title, bool? Done, [property: Range(1, 3)] int? Priority);