الموارد وURLs
جزء من قسم واجهات API بنمط REST في رحلة ASP.NET Core على Coddy. الدرس 1 من 20.
تستدعي برامج أخرى واجهة API الخاصة بك، لذا ينبغي أن تكون عناوين URL الخاصة بها سهلة التخمين. تتبع معظم واجهات API للويب أسلوبًا يُسمى REST: يحدد كل عنوان URL موردًا، أي شيئًا تخزّنه واجهة API، وتحدد طريقة HTTP الإجراء الذي ينبغي تنفيذه عليه.
GET /api/invoices the list of invoices
GET /api/invoices/7 invoice 7
POST /api/invoices add an invoice
DELETE /api/invoices/7 remove invoice 7تحتوي المسارات على أسماء، وليس أفعالًا أبدًا: مع /api/getInvoice?id=7، يتعين على كل عميل تعلم كلمة جديدة لكل إجراء. يكون اسم المجموعة بصيغة الجمع، ويكون مسار العنصر الواحد هو مسار المجموعة مضافًا إليه معرّفه.
app.MapGet("/api/invoices/{id:int}", (int id) =>
{
var invoice = invoices.Find(i => i.Id == id);
return invoice is null ? Results.NotFound() : Results.Ok(invoice);
});{id:int} هو مُعامل مسار يتضمن قيدًا: فهو يطابق الأعداد الصحيحة فقط، لذا لا يطابق /api/invoices/abc أي مسار، ويُرجع استجابة 404. ويُرجع 404 أيضًا إذا لم يطابق المعرّف أي فاتورة، وذلك عبر Results.NotFound().
التحدي
سهلفي هذا القسم، ستبني واجهة API لتتبّع المهام. تبدأ بثلاث مهام وGET /api/tasks، الذي يعرضها كلها. المهام هي سجلات TaskItem، لأن .NET يتضمن بالفعل نوعًا يُسمى Task. أضف عنوان URL لمهمة واحدة.
- في
Program.cs، أسفلGET /api/tasks، اربطGET /api/tasks/{id:int}. - ابحث عن المهمة التي تكون قيمة
Idفيها مساوية لـidباستخدامtasks.Find، وأعِدها باستخدامResults.Ok(task). يعرضGET /api/tasks/2ما يلي:{ "id": 2, "title": "Book the meeting room", "done": true } - عندما لا تكون هناك مهمة بهذا المعرّف، أجب باستخدام
Results.NotFound(): الحالة 404 مع متن فارغ.
جرّب ذلك: اضغط على «تشغيل». يرسل العمود GET /api/tasks ويعرض المهام الثلاث. أرسل GET /api/tasks/2: ستحصل على 200 والمهمة أعلاه. أرسل GET /api/tasks/99: ستحصل على 404. أرسل GET /api/tasks/abc: ستحصل على 404 أيضًا، لأن {id:int} لا يطابق إلا الأرقام.
جرّب بنفسك
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var tasks = new List<TaskItem>
{
new(1, "Write the project brief", false),
new(2, "Book the meeting room", true),
new(3, "Send the invoice", false),
};
app.MapGet("/api/tasks", () => tasks);
app.Run();
record TaskItem(int Id, string Title, bool Done);
يتضمن هذا الدرس اختبارًا قصيرًا. ابدأ الدرس للإجابة عليه وتتبّع تقدمك.
جميع دروس واجهات API بنمط REST
1الموارد والأفعال
الموارد وURLsالإنشاء باستخدام POST