The five design elements

عناصر التصميم الخمسة

Slides 20 and 24 list what you must decide when designing a REST API. Learn them in order, with the one-line content slide 24 gives each:

تسرد الشريحتان 20 و24 ما يجب أن تقرره عند تصميم واجهة REST. احفظها بالترتيب، مع السطر الذي تعطيه الشريحة 24 لكل عنصر:

يلخّص الجدول العناصر الخمسة وأين يسافر كل منها داخل رسالة HTTP. لاحظ أن رمز الحالة هو العنصر الوحيد الذي يوجد في الاستجابة فقط، وأن JSON يصف إما حالة المورد (في الاستجابة) وإما التغيير المطلوب (في الطلب).

العنصر 1 (URL) والعنصر 2 (الطريقة) يفتتحان الطلب. والعنصر 3 (رمز الحالة) يفتتح الاستجابة. أما 4 (الترويسات) و5 (JSON) فيظهران في الجهتين.

The design principles behind the elements

مبادئ التصميم وراء العناصر

Slide 21 states four practical rules that the five elements implement:

تذكر الشريحة 21 أربع قواعد عملية تطبّقها العناصر الخمسة:

1. Every entity is a resource (a file, a user, a virtual machine, an IoT device), and each resource is uniquely identified by a URI such as /lamps/123.

   كل كيان مورد (resource): ملف، مستخدم، آلة افتراضية، جهاز IoT. وكل مورد له URI فريد مثل /lamps/123.

2. A resource is represented in JSON, using key-value pairs, and representations are exchanged through HTTP request and response bodies.

   يُمثَّل المورد بـ JSON باستخدام أزواج مفتاح وقيمة (key-value pairs)، وتُتبادل التمثيلات عبر أجسام طلبات واستجابات HTTP.

3. Extra information goes in HTTP headers: authentication tokens, content types, and accepted response formats.

   المعلومات الإضافية توضع في ترويسات HTTP: رموز المصادقة (tokens)، ونوع المحتوى، وصيغ الاستجابة المقبولة.

4. Communication is stateless: each request contains what the server needs to process it independently.

   الاتصال عديم الحالة: كل طلب يحمل ما يحتاجه الخادم لمعالجته بشكل مستقل.

Design example 1: lamps in a home

مثال التصميم 1: المصابيح في منزل

Slide 22 sets the scene: a browser page at .../lamp/123 with ON, OFF and an intensity slider sends an HTTP request to a small server (a Raspberry Pi in the picture), which sends a signal to the device with ID 123. Slide 23 is the solution table. Two URLs: the collection http://myHome.com/lamps and the item http://myHome.com/lamps/123.

الشريحة 22 ترسم المشهد: صفحة متصفح على .../lamp/123 فيها أزرار ON وOFF ومنزلق للشدة، ترسل طلب HTTP إلى خادم صغير (Raspberry Pi في الصورة)، والخادم يرسل إشارة إلى الجهاز رقم 123. والشريحة 23 هي جدول الحل. هناك عنوانان: المجموعة (collection) http://myHome.com/lamps والعنصر (item) http://myHome.com/lamps/123.

هذا جدول الحل في الشريحة 23. ما يجب ملاحظته: GET وDELETE وPOST يعود فيها JSON داخل الاستجابة، أما PUT فهو الوحيد الذي يُرسَل فيه JSON داخل الطلب. وDELETE هنا يعني تعطيل المصباح ("Enabled": false) لا إزالته. وPOST على العنصر /lamps/123 غير منطبق، لأن الإنشاء يتم على المجموعة. والترويسات لكل الصفوف هي Cookie وAuthentication Token وAuthorization Token.

Header fields for every row: Cookie, Authentication Token, Authorization Token. Notice the new lamp found by POST starts life enabled but off at brightness 0.

الترويسات في كل الصفوف: Cookie، Authentication Token، Authorization Token. ولاحظ أن المصباح الجديد الذي يكتشفه POST يبدأ مُفعَّلاً (Enabled) لكنه مطفأ وسطوعه 0.

Design example 2: the calculator

مثال التصميم 2: الآلة الحاسبة

Slide 25 asks: design a REST API for the addition operation, which must happen on the server. Slide 26 fills the five elements:

تطلب الشريحة 25: صمّم واجهة REST لعملية الجمع بحيث تتم على الخادم. والشريحة 26 تملأ العناصر الخمسة:

هذا جدول الشريحة 26 كما هو. احفظه حرفياً: URL هو http://calculator.com/add، والطريقة GET، والترويسة Authorization، والرسالة {"X": 1, "Y": 2}. رموز الحالة خمسة: 200 و400 و406 و500 و503.

request   GET http://calculator.com/add
          Authorization: Bearer eyJ...
          { "X": 1, "Y": 2 }

server    X  = 1
          Y  = 2
          op = Addition        (chosen by the path /add)
          Resp.send(X op Y)  =  Resp.send(1 + 2)  =  3

response  200 OK   with the result 3

body is { "X": 1 }  (Y missing)            -> 400 bad request
client sends Accept: application/xml,
  server can only produce JSON            -> 406 not acceptable
server code throws an exception           -> 500 internal server error
server overloaded or down for maintenance -> 503 service unavailable

Status code classes

فئات رموز الحالة

Slide 24 says status codes run from 100 to 599. The first digit tells you the class, which is all you need for a matching question:

تقول الشريحة 24 إن رموز الحالة من 100 إلى 599. الرقم الأول يحدد الفئة، وهذا كل ما تحتاجه لسؤال matching:

الفئات الخمس تتحدد بالرقم الأول: 1xx معلوماتية، 2xx نجاح، 3xx إعادة توجيه، 4xx خطأ من العميل، 5xx خطأ من الخادم. الخلايا المظللة تحتوي رموز الشريحة 26. أما 201 و204 و301 و304 و401 و403 و404 فهي إضافات شائعة من خارج الشريحة.