Menu
CoddyTech

الموارد و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().

challenge icon

التحدي

سهل

في هذا القسم، ستبني واجهة API لتتبّع المهام. تبدأ بثلاث مهام وGET /api/tasks، الذي يعرضها كلها. المهام هي سجلات TaskItem، لأن .NET يتضمن بالفعل نوعًا يُسمى Task. أضف عنوان URL لمهمة واحدة.

  1. في Program.cs، أسفل GET /api/tasks، اربط GET /api/tasks/{id:int}.
  2. ابحث عن المهمة التي تكون قيمة Id فيها مساوية لـ id باستخدام tasks.Find، وأعِدها باستخدام Results.Ok(task). يعرض GET /api/tasks/2 ما يلي:
    { "id": 2, "title": "Book the meeting room", "done": true }
  3. عندما لا تكون هناك مهمة بهذا المعرّف، أجب باستخدام 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);
quiz iconاختبر نفسك

يتضمن هذا الدرس اختبارًا قصيرًا. ابدأ الدرس للإجابة عليه وتتبّع تقدمك.

جميع دروس واجهات API بنمط REST