Application Programming Interfaces (APIs)واجهات برمجة التطبيقات (APIs)

Open a weather app on your phone. The screen that draws today's temperature is the frontend. The database of sensor readings sitting in a data center is the backend. The phone never opens that database directly, and the database knows nothing about pixels. Something in between answers "give me today's readings for Dhahran" and, when you submit a correction, "store this new reading". That something is an Application Programming Interface (API).

افتح تطبيق الطقس على هاتفك. الشاشة التي ترسم درجة حرارة اليوم هي الواجهة الأمامية (frontend). وقاعدة بيانات قراءات المستشعرات الموجودة في مركز بيانات هي الخلفية (backend). الهاتف لا يفتح تلك القاعدة مباشرة أبدًا، والقاعدة لا تعرف شيئًا عن البكسلات. هناك شيء في المنتصف يجيب عن "أعطني قراءات اليوم للظهران"، وعندما ترسل تصحيحًا يجيب عن "خزّن هذه القراءة الجديدة". ذلك الشيء هو واجهة برمجة التطبيقات Application Programming Interface (API).

The lecture's definition is short: an API allows different software components to communicate with each other, and it acts as the interface between components. The word that matters is interface. MDN describes an API as a simple contract between the application offering it and the software that uses it: the provider promises which requests it will accept and what it will send back, and the caller promises to ask only in those terms. Neither side needs to see inside the other.

تعريف المحاضرة قصير: الـ API يسمح لمكوّنات برمجية مختلفة بأن تتواصل فيما بينها، وهو يعمل كواجهة بين المكوّنات. الكلمة المهمة هي الواجهة (interface). يصف موقع MDN الـ API بأنه عقد بسيط بين التطبيق الذي يقدّمه والبرنامج الذي يستخدمه: المزوّد يتعهد بالطلبات التي سيقبلها وبما سيعيده، والمستدعي يتعهد بألا يطلب إلا بتلك الشروط. ولا يحتاج أي طرف إلى رؤية ما بداخل الطرف الآخر.

The middle layer and its two jobsالطبقة الوسطى ومهمتاها

The lecture draws the application as three stacked boxes: frontend on top, backend at the bottom, and the API layer (the middle layer) between them. Every interaction between top and bottom goes through the middle, and it flows in one of two directions.

ترسم المحاضرة التطبيق على شكل ثلاثة صناديق متراصّة: الواجهة الأمامية في الأعلى، والخلفية في الأسفل، وAPI layer (الطبقة الوسطى) بينهما. كل تفاعل بين الأعلى والأسفل يمر عبر الوسط، ويسير في أحد اتجاهين.

1. Read path: the API layer fetches data from the backend and hands it up to be displayed on the frontend. The weather app showing today's temperature is this path.مسار القراءة (read path): تجلب طبقة الـ API البيانات من الخلفية وتسلّمها إلى الأعلى لتُعرض على الواجهة الأمامية. تطبيق الطقس الذي يعرض حرارة اليوم هو هذا المسار.
2. Write path: the API layer takes data from the frontend and inserts it into the backend. The correction you submit is this path.مسار الكتابة (write path): تأخذ طبقة الـ API البيانات من الواجهة الأمامية وتدخلها في الخلفية. التصحيح الذي ترسله هو هذا المسار.

In the visual, the left arrows are the read path (fetch, then display) and the right arrows are the write path (take, then insert). Every arrow starts or ends at the middle box; none jumps straight from frontend to backend. That is the whole point of a middle layer: if the backend swaps its database engine, or the frontend is rewritten from a web page into a mobile app, only one side of the contract changes and the other keeps working.

في الرسم، الأسهم اليسرى هي مسار القراءة (جلب ثم عرض) والأسهم اليمنى هي مسار الكتابة (أخذ ثم إدخال). كل سهم يبدأ أو ينتهي عند الصندوق الأوسط، ولا يقفز أي سهم مباشرة من الواجهة الأمامية إلى الخلفية. وهذا هو جوهر وجود طبقة وسطى: إذا غيّرت الخلفية محرك قاعدة البيانات، أو أُعيدت كتابة الواجهة الأمامية من صفحة ويب إلى تطبيق جوال، يتغير طرف واحد فقط من العقد ويستمر الطرف الآخر في العمل.

Connect this to Lecture 01. There, a relationship between two components was defined as a protocol plus an interface. The API is precisely the interface half: the set of operations one component offers the other. The next concept fills in the protocol half and adds a third piece underneath.

اربط هذا بالمحاضرة 01. هناك عُرّفت العلاقة بين مكوّنين بأنها بروتوكول زائد واجهة. والـ API هو بالضبط نصف الواجهة: مجموعة العمليات التي يقدّمها مكوّن للآخر. المفهوم التالي يملأ نصف البروتوكول ويضيف قطعة ثالثة تحته.

Take the lamp from Lecture 01 and send it one request: GET /lamp/energy. Three separate things have to be true for that request to work, and each one answers a different question.

خذ المصباح من المحاضرة 01 وأرسل إليه طلبًا واحدًا: GET /lamp/energy. يجب أن تتحقق ثلاثة أشياء منفصلة لكي ينجح هذا الطلب، وكل واحد منها يجيب عن سؤال مختلف.

1. The server must offer an operation called "read energy" at /lamp/energy. If it does not, nothing else matters. That is the question of what you can call.يجب أن يقدّم الخادم عملية اسمها "قراءة الطاقة" (read energy) عند /lamp/energy. إن لم يفعل، فلا شيء آخر يهم. هذا هو سؤال ماذا يمكنك أن تستدعي.
2. The client must phrase the request in a format the server understands: a method (GET), a target path, a version, headers, and later a status code in the reply. That is the question of how you call it.يجب أن يصوغ العميل الطلب بصيغة يفهمها الخادم: طريقة (GET)، ومسار هدف (target path)، ونسخة (version)، وترويسات (headers)، ثم لاحقًا رمز حالة (status code) في الرد. هذا هو سؤال كيف تستدعيه.
3. The bytes of that request must actually reach the server: through a TCP connection between two sockets, IP packets across routers, and frames over Wi-Fi or Ethernet. That is the question of how the data physically travels.يجب أن تصل بايتات ذلك الطلب فعلًا إلى الخادم: عبر اتصال TCP بين مقبسين (sockets)، وحزم IP عبر الموجّهات (routers)، وإطارات (frames) عبر Wi-Fi أو Ethernet. هذا هو سؤال كيف تنتقل البيانات فعليًا.

Slide 3 compresses this into the single most quotable line of the lecture. Learn it word for word.

تختصر الشريحة 3 هذا كله في أكثر سطر قابل للاقتباس في المحاضرة. احفظه حرفيًا.

The slide's picture says the same thing for two components that each carry a Web API port. The API is the interface between them: a Web API is the interface, and HTTP is the protocol used to implement the communication. The line underneath is the connection, the physical path the data takes.

صورة الشريحة تقول الشيء نفسه لمكوّنين يحمل كل منهما منفذ Web API. الـ API هو الواجهة بينهما: Web API هو الواجهة، وHTTP هو protocol (البروتوكول) المستخدم لتنفيذ التواصل. والخط الذي تحتهما هو connection (الاتصال)، أي المسار المادي الذي تسلكه البيانات.

Read the visual from the top. The three small squares in the top band are the operations the API offers (the Web API ports on the slide). The middle band is the HTTP request that names one of them. The bottom band is the wire that carries the bytes from one end to the other.

اقرأ الرسم من الأعلى. المربعات الثلاثة الصغيرة في الشريط العلوي هي العمليات التي يقدّمها الـ API (منافذ Web API في الشريحة). الشريط الأوسط هو طلب HTTP الذي يسمّي واحدة منها. والشريط السفلي هو السلك الذي يحمل البايتات من طرف إلى الطرف الآخر.

Where each layer lives in the TCP/IP stackأين تقع كل طبقة في مكدّس TCP/IP

This is not new material wearing a new name; it is the stack from Lecture 01 seen from the application's point of view. HTTP is an application-layer protocol. Everything under it (TCP at the transport layer, IP at the network layer, then the link and physical layers) is what the lecture now calls the connection. The socket you met in Lecture 01 is the door between the two: the program writes its HTTP message into a socket, and from there the connection takes over. RFC 9110 states the same split from the protocol side: HTTP operates over a reliable transport or session-layer connection, and HTTP itself is independent of the transport protocol.

هذه ليست مادة جديدة باسم جديد؛ إنها المكدّس من المحاضرة 01 منظورًا إليه من جهة التطبيق. HTTP بروتوكول في طبقة التطبيق (application layer). وكل ما تحته (TCP في طبقة النقل، وIP في طبقة الشبكة، ثم طبقتا الربط والطبقة المادية) هو ما تسميه المحاضرة الآن الاتصال (connection). والمقبس (socket) الذي رأيته في المحاضرة 01 هو الباب بين الاثنين: يكتب البرنامج رسالة HTTP في المقبس، ومن هناك يتولى الاتصال الأمر. ويذكر RFC 9110 التقسيم نفسه من جهة البروتوكول: يعمل HTTP فوق اتصال نقل موثوق أو اتصال في طبقة الجلسة (session layer)، وHTTP نفسه مستقل عن بروتوكول النقل.

Why three layers and not one: the swap testلماذا ثلاث طبقات وليست واحدة: اختبار الاستبدال

The best evidence that these are three different things is that each can change while the others stay put.

أقوى دليل على أن هذه ثلاثة أشياء مختلفة هو أن كل واحد منها يمكن أن يتغير بينما يبقى الآخران كما هما.

• Change the API only. Add a brightness operation at /lamp/brightness. The protocol is still HTTP and the wire is still TCP over Wi-Fi.غيّر الـ API فقط. أضف عملية للسطوع عند /lamp/brightness. يبقى البروتوكول HTTP ويبقى السلك TCP عبر Wi-Fi.
• Change the connection only. Move the lamp from Wi-Fi to Ethernet. The same HTTP requests reach the same operations. HTTP/3 goes further and runs over QUIC instead of TCP; RFC 9114 describes it as supporting the same semantics over a new transport protocol, so the API the client sees does not change.غيّر الاتصال فقط. انقل المصباح من Wi-Fi إلى Ethernet. تصل طلبات HTTP نفسها إلى العمليات نفسها. ويذهب HTTP/3 أبعد من ذلك فيعمل فوق QUIC بدلًا من TCP؛ ويصفه RFC 9114 بأنه يدعم الدلالات (semantics) نفسها فوق بروتوكول نقل جديد، لذلك لا يتغير الـ API الذي يراه العميل.
• Reuse the protocol. The same HTTP carries millions of unrelated APIs, from lamps to banks.أعد استخدام البروتوكول. بروتوكول HTTP نفسه يحمل ملايين الـ APIs التي لا علاقة بينها، من المصابيح إلى البنوك.

Picture a smart-home server that manages lamps, a thermostat and user accounts. A phone app, the HTTP client, sends it many requests: one about a lamp, one about the temperature, one about the logged-in user. The HTTP server does not answer them all from one undifferentiated blob of code. It has several doors, and each request is answered at the door responsible for it.

تخيّل خادم منزل ذكي يدير مصابيح وجهاز تحكم في الحرارة (thermostat) وحسابات مستخدمين. تطبيق الهاتف، أي HTTP client، يرسل إليه طلبات كثيرة: واحد عن مصباح، وواحد عن درجة الحرارة، وواحد عن المستخدم المسجّل دخوله. لا يجيب HTTP server عنها كلها من كتلة واحدة غير متمايزة من الكود. بل له عدة أبواب، ويُجاب عن كل طلب عند الباب المسؤول عنه.

Slide 4 names those doors: the API on the server is also referred to as an endpoint. The client sends multiple requests, the server has multiple endpoints (drawn as boxes 1, 2 and 3 on its edge), and the endpoint is where the API processes the request and returns data. So an endpoint is not a network address and not a machine; it is a point on the server's boundary where requests arrive and responses leave.

تسمّي الشريحة 4 تلك الأبواب: يُشار إلى الـ API على الخادم أيضًا باسم endpoint (نقطة النهاية). يرسل العميل طلبات متعددة، وللخادم نقاط نهاية متعددة (مرسومة كصناديق 1 و2 و3 على حافته)، ونقطة النهاية هي المكان الذي يعالج فيه الـ API الطلب ويعيد البيانات. إذن نقطة النهاية ليست عنوان شبكة وليست جهازًا؛ إنها نقطة على حدود الخادم تصل إليها الطلبات وتخرج منها الاستجابات.

What an endpoint stands forما الذي تمثّله نقطة النهاية

Slide 5 asks the deeper question: what does an endpoint represent? Its answer has three parts, and each is worth a mark.

تطرح الشريحة 5 السؤال الأعمق: ماذا تمثّل نقطة النهاية؟ لجوابها ثلاثة أجزاء، وكل جزء يستحق درجة.

1. An endpoint is an abstraction of a resource. The client interacts with an endpoint that manages a resource. A resource is any entity the server manages: a file, a user, a virtual machine, an IoT lamp. RFC 9110 is explicit that HTTP does not limit the nature of a resource; it only defines an interface for interacting with one.نقطة النهاية تجريد (abstraction) لمورد. يتعامل العميل مع نقطة نهاية تدير resource (موردًا). المورد هو أي كيان يديره الخادم: ملف، أو مستخدم، أو آلة افتراضية، أو مصباح IoT. ويصرّح RFC 9110 بأن HTTP لا يقيّد طبيعة المورد؛ بل يعرّف فقط واجهة للتعامل معه.
2. An endpoint supports four basic operations on that resource, known as CRUD: Create, Read, Update, Delete.تدعم نقطة النهاية أربع عمليات أساسية على ذلك المورد، تُعرف باسم CRUD: Create (إنشاء)، وRead (قراءة)، وUpdate (تحديث)، وDelete (حذف).
3. An endpoint provides the logic needed to execute those four operations on the resource: validating input, checking the current state, talking to the database or the device.توفر نقطة النهاية المنطق اللازم لتنفيذ هذه العمليات الأربع على المورد: التحقق من المدخلات، وفحص الحالة الحالية، والتخاطب مع قاعدة البيانات أو الجهاز.

"Abstraction" is the key word. Lamp 7 is, in reality, a row in a database and a relay on a GPIO pin. The client sees neither. It sees a lamp it can create, read, update and delete, and the endpoint translates those four verbs into whatever the real resource needs. The slide's summary line follows: endpoints act as access points for retrieving or modifying resources.

"التجريد" (abstraction) هو الكلمة المفتاحية. المصباح 7 في الواقع صف في قاعدة بيانات ومرحّل (relay) على منفذ GPIO. والعميل لا يرى أيًّا منهما. بل يرى مصباحًا يمكنه إنشاؤه وقراءته وتحديثه وحذفه، ونقطة النهاية تترجم هذه الأفعال الأربعة إلى ما يحتاجه المورد الحقيقي. ومن هنا يأتي سطر الخلاصة في الشريحة: تعمل نقاط النهاية كنقاط وصول لاسترجاع الموارد أو تعديلها.

Reading the arrows as data flowقراءة الأسهم على أنها تدفق للبيانات

Look at the direction of the four arrows on slide 5. Create, Update and Delete point from the endpoint to the resource; Read points from the resource back to the endpoint. The slide is drawing which way the data moves. Creating, updating and deleting push a change into the resource. Reading pulls the resource's state out toward the client.

انظر إلى اتجاه الأسهم الأربعة في الشريحة 5. أسهم Create وUpdate وDelete تتجه من نقطة النهاية إلى المورد؛ وسهم Read يتجه من المورد عائدًا إلى نقطة النهاية. الشريحة ترسم الاتجاه الذي تتحرك فيه البيانات. الإنشاء والتحديث والحذف تدفع تغييرًا إلى داخل المورد. أما القراءة فتسحب حالة المورد إلى الخارج نحو العميل.

In the visual, three arrows draw toward the resource and one draws back. Notice that the client never touches the resource box; its only line ends at the endpoint.

في الرسم، ثلاثة أسهم تُرسم نحو المورد وسهم واحد يُرسم عائدًا. لاحظ أن العميل لا يلمس صندوق المورد أبدًا؛ فخطه الوحيد ينتهي عند نقطة النهاية.

A client wants to switch lamp 7 off, not read it and not delete it. The endpoint for lamp 7 supports all four CRUD operations, so the request must say which one. It does that with two pieces of information together: the URL that leads to the endpoint, and the HTTP method that picks the operation.

يريد عميل أن يطفئ المصباح 7، لا أن يقرأه ولا أن يحذفه. نقطة النهاية الخاصة بالمصباح 7 تدعم عمليات CRUD الأربع كلها، لذلك يجب أن يحدد الطلب أيّها يريد. ويفعل ذلك بمعلومتين معًا: عنوان URL الذي يقود إلى نقطة النهاية، وطريقة HTTP التي تختار العملية.

• GET /lamps/7 reads lamp 7.GET /lamps/7 يقرأ المصباح 7.
• PUT /lamps/7 updates lamp 7, for example to switch it off.PUT /lamps/7 يحدّث المصباح 7، مثلًا لإطفائه.
• DELETE /lamps/7 deletes (or disables) lamp 7.DELETE /lamps/7 يحذف المصباح 7 (أو يعطّله).
• POST /lamps creates a new lamp. Its URL differs because the new lamp has no number yet; Part 3 of this lecture explains why creation goes to the collection.POST /lamps ينشئ مصباحًا جديدًا. عنوانه مختلف لأن المصباح الجديد ليس له رقم بعد؛ ويشرح الجزء 3 من هذه المحاضرة لماذا يذهب الإنشاء إلى المجموعة (collection).

Each of those pairs is a route. Slide 6 states the rule: a URL leads to an endpoint, which defines routes to manage different actions, and a route is an HTTP method plus a URL. A resource can therefore be exposed through multiple API operations, typically distinguished by HTTP methods and URL paths.

كل زوج من هذه الأزواج هو route (مسار). تذكر الشريحة 6 القاعدة: عنوان URL يقود إلى نقطة نهاية، ونقطة النهاية تعرّف مسارات لإدارة أفعال مختلفة، والمسار هو HTTP method زائد عنوان URL. لذلك يمكن عرض المورد الواحد عبر عدة عمليات API، تُميَّز عادة بطرق HTTP ومسارات URL.

The visual shows why both halves are needed. Three of the four routes share the URL /lamps/7, so the URL alone cannot tell Read from Update from Delete. And GET appears on many endpoints across a server, so the method alone cannot tell lamp 7 from the thermostat. Only the pair is unique. That is exactly how server frameworks dispatch requests: Express, for instance, runs a handler only when both the path and the HTTP method match.

يبيّن الرسم لماذا نحتاج إلى النصفين معًا. ثلاثة من المسارات الأربعة تشترك في العنوان /lamps/7، لذلك لا يستطيع العنوان وحده أن يميّز Read من Update من Delete. وGET تظهر على نقاط نهاية كثيرة في الخادم، لذلك لا تستطيع الطريقة وحدها أن تميّز المصباح 7 من جهاز التحكم في الحرارة. الزوج وحده هو الفريد. وهكذا بالضبط توزّع أطر عمل الخوادم الطلبات: Express مثلًا لا يشغّل المعالج (handler) إلا عندما يتطابق المسار وطريقة HTTP كلاهما.

The bottom box of slide 6 ties the three roles together, and it is a ready-made exam answer:

الصندوق السفلي في الشريحة 6 يربط الأدوار الثلاثة معًا، وهو إجابة جاهزة للامتحان:

• The server hosts the endpoint.الخادم يستضيف نقطة النهاية.
• The client communicates with the endpoint via specific routes.العميل يتواصل مع نقطة النهاية عبر مسارات (routes) محددة.
• The routes correspond to CRUD operations on the endpoint.المسارات تقابل عمليات CRUD على نقطة النهاية.

From the client's side: the server is a set of APIsمن جهة العميل: الخادم مجموعة من الـ APIs

Now stand where the client stands. It cannot see the server's language, its database or its hardware. It sends a request and gets a response, and the only thing it knows about the server is the list of routes it may call. Slide 7 puts it plainly: for the client, the HTTP server is a set of APIs. Each numbered box on the server's edge is one API the client can address, and the same request and response pattern repeats at every one.

الآن قف حيث يقف العميل. إنه لا يرى لغة الخادم ولا قاعدة بياناته ولا عتاده. يرسل طلبًا ويتلقى استجابة، والشيء الوحيد الذي يعرفه عن الخادم هو قائمة المسارات التي يجوز له استدعاؤها. تقولها الشريحة 7 بوضوح: بالنسبة إلى العميل، خادم HTTP مجموعة من الـ APIs. كل صندوق مرقّم على حافة الخادم هو API واحد يستطيع العميل مخاطبته، ونمط الطلب والاستجابة نفسه يتكرر عند كل واحد منها.

This is the client-server idea from Lecture 01 with the interior hidden. It is also what makes the rest of the course possible: if the client only knows the set of APIs, the server behind them can be moved from a board next to the lamp to an edge node or a cloud region without the client noticing.

هذه فكرة العميل والخادم (client-server) من المحاضرة 01 مع إخفاء ما بالداخل. وهي أيضًا ما يجعل بقية المقرر ممكنًا: إذا كان العميل لا يعرف إلا مجموعة الـ APIs، فيمكن نقل الخادم الذي خلفها من لوحة بجانب المصباح إلى عقدة طرفية (edge node) أو إلى منطقة سحابية (cloud region) دون أن يلاحظ العميل.

Think of a smart lamp exposed through an API. You might add a new lamp to the system, ask for its current state, set it to a new state, or retire it. Those four actions are all an application ever does to stored data, and HTTP has one verb for each.

تخيّل مصباحًا ذكيًا متاحًا عبر API. قد تضيف مصباحًا جديدًا إلى النظام، أو تسأل عن حالته الحالية، أو تضبطه على حالة جديدة، أو تُخرجه من الخدمة. هذه الأفعال الأربعة هي كل ما يفعله أي تطبيق بالبيانات المخزنة، ولـ HTTP فعل واحد لكل منها.

The table to memorizeالجدول الذي يجب حفظه

The four actions are the CRUD operations: Create, Read, Update, Delete. Each request names its operation with an HTTP method, the verb at the very start of the message. The lecture maps them like this: POST creates a new Resource, GET returns one, PUT updates or replaces one, and DELETE removes one.

الأفعال الأربعة هي عمليات CRUD: الإنشاء (Create)، والقراءة (Read)، والتحديث (Update)، والحذف (Delete). كل طلب يسمّي عمليته بـ HTTP method، وهو الفعل الموجود في بداية الرسالة تمامًا. وتربطها المحاضرة هكذا: POST ينشئ resource جديدًا، وGET يُرجع موردًا، وPUT يحدّث موردًا أو يستبدله، وDELETE يحذفه.

Slide 8 lists GET first. Slide 9 lists the same four in CRUD order, so POST comes first. The mapping is identical; only the row order changed. If an exam table is shuffled, anchor on the pair people swap: you POST a new item (Create) and GET an existing one (Read). DELETE is Delete, and PUT is the one left, Update.

الشريحة 8 تضع GET أولًا. والشريحة 9 تسرد الطرق الأربع نفسها بترتيب CRUD، فتأتي POST أولًا. الربط متطابق؛ لم يتغير إلا ترتيب الصفوف. إذا جاء جدول في الامتحان مخلوط الترتيب، فاعتمد على الزوج الذي يخلط الناس بينه: ترسل عنصرًا جديدًا بـ POST (إنشاء)، وتجلب عنصرًا موجودًا بـ GET (قراءة). DELETE هي الحذف، وPUT هي المتبقية، أي التحديث.

PUT replaces, PATCH editsPUT يستبدل، وPATCH يعدّل

The slides write PUT as "Update / Replace", and the word replace is the precise one. A PUT sends the full new state of the resource at a URL the client already knows, and the server stores exactly that. If you PUT a lamp with only a brightness field, a strict server would forget the lamp's colour. For changing one field there is PATCH, defined in RFC 5789, which sends only a set of changes. PATCH does not appear in the tables on slides 8 and 9, but it appears on slide 19, so meet it now.

تكتب الشرائح PUT على أنها "Update / Replace"، وكلمة الاستبدال (replace) هي الأدق. طلب PUT يرسل الحالة الجديدة الكاملة للمورد إلى URL يعرفه العميل مسبقًا، والخادم يخزّن ذلك بالضبط. إذا أرسلت PUT لمصباح بحقل السطوع (brightness) فقط، فإن الخادم الصارم سينسى لون المصباح. لتغيير حقل واحد توجد PATCH، المعرّفة في RFC 5789، وهي ترسل مجموعة من التغييرات فقط. لا تظهر PATCH في جدولي الشريحتين 8 و9، لكنها تظهر في الشريحة 19، لذا تعرّف عليها الآن.

Beyond the slides: safe and idempotentخارج الشرائح: الآمن (safe) ومتساوي الأثر (idempotent)

A method is safe when it does not ask the server to change anything. GET is safe: reading a lamp's state never turns it on. That is why browsers, caches and crawlers feel free to send GET requests on their own.

تكون الطريقة آمنة (safe) عندما لا تطلب من الخادم تغيير أي شيء. GET آمنة: قراءة حالة المصباح لا تشغّله أبدًا. ولهذا تشعر المتصفحات والـ caches وبرامج الزحف (crawlers) بحرية إرسال طلبات GET من تلقاء نفسها.

A method is Idempotent method when sending the same request twice leaves the server in the same state as sending it once. Picture a flaky mobile connection: the app sends a request, the reply is lost, and the app retries. Whether the retry is harmless depends on the method.

تكون الطريقة idempotent (متساوية الأثر) عندما يترك إرسال الطلب نفسه مرتين الخادمَ في الحالة نفسها التي يتركه فيها إرساله مرة واحدة. تخيّل اتصال جوال متقطعًا: يرسل التطبيق طلبًا، فيضيع الرد، فيعيد التطبيق المحاولة. كون إعادة المحاولة غير ضارة يعتمد على الطريقة.

• PUT /lamps/7 with state "on", sent twice: the lamp is "on" after the first and still "on" after the second. Idempotent.PUT /lamps/7 بالحالة "on"، مرسلًا مرتين: المصباح "on" بعد الأول وما زال "on" بعد الثاني. متساوية الأثر (idempotent).
• DELETE /lamps/7 sent twice: the first removes it, the second finds nothing. The response codes differ (often 200 then 404), but the end state, no lamp 7, is the same. Idempotent.DELETE /lamps/7 مرسلًا مرتين: الأول يحذفه، والثاني لا يجد شيئًا. رموز الاستجابة تختلف (غالبًا 200 ثم 404)، لكن الحالة النهائية، أي عدم وجود المصباح 7، هي نفسها. متساوية الأثر (idempotent).
• GET /lamps/7 sent twice: nothing changes at all. Safe, and therefore idempotent.GET /lamps/7 مرسلًا مرتين: لا يتغير أي شيء على الإطلاق. آمنة، وبالتالي متساوية الأثر.
• POST /lamps sent twice: two new lamps with two new IDs. Not idempotent.POST /lamps مرسلًا مرتين: مصباحان جديدان بمعرّفين (IDs) جديدين. ليست متساوية الأثر.

Type http://localhost/index.html into a browser. Before any page appears, the browser, acting as an HTTP client, writes a short text message and sends it to the HTTP server on your own machine.

اكتب http://localhost/index.html في المتصفح. قبل أن تظهر أي صفحة، يكتب المتصفح، بصفته HTTP client، رسالة نصية قصيرة ويرسلها إلى HTTP server على جهازك نفسه.

On the server side the lecture draws the picture of part 01: the Endpoint receives the request, reads the resource from the server's file system, and sends it back. Here the resource is a static file, index.html, so "reading" just means opening the file. Later in the lecture the same pattern will read a lamp's state from a database instead.

على جانب الخادم ترسم المحاضرة صورة الجزء 01: الـ endpoint يستقبل الطلب، ويقرأ المورد من نظام ملفات الخادم، ثم يعيده. هنا المورد ملف ثابت، index.html، لذا فإن "القراءة" تعني ببساطة فتح الملف. لاحقًا في المحاضرة سيقرأ النمط نفسه حالة المصباح من قاعدة بيانات بدلًا من ذلك.

The URL is split across the messageالـ URL يتوزع على أجزاء الرسالة

The URL does not travel as one piece. The host part, localhost, is used to find and connect to the server, and is repeated inside the message as the Host header. The path part, /index.html, goes into the first line. Here is the full request from slide 11:

الـ URL لا ينتقل قطعة واحدة. جزء المضيف (host)، أي localhost، يُستخدم لإيجاد الخادم والاتصال به، ويتكرر داخل الرسالة في ترويسة Host. وجزء المسار (path)، أي /index.html، يذهب إلى السطر الأول. وهذا هو الطلب الكامل من الشريحة 11:

The first line is the Request line. Its grammar in the HTTP/1.1 standard is exact: method, single space, request target, single space, version.

السطر الأول هو request line (سطر الطلب). وقواعده في معيار HTTP/1.1 دقيقة: الطريقة، ثم مسافة واحدة، ثم هدف الطلب، ثم مسافة واحدة، ثم الإصدار.

1. Request line: GET /index.html HTTP/1.1.سطر الطلب: GET /index.html HTTP/1.1.
2. Zero or more Header fields, one per line, each a name, a colon and a value.صفر أو أكثر من header fields (حقول الترويسة)، حقل في كل سطر، وكل حقل اسم ثم نقطتان رأسيتان (:) ثم قيمة.
3. An empty line (just CRLF, the two characters carriage return and line feed).سطر فارغ (مجرد CRLF، أي الحرفين: الرجوع إلى بداية السطر (carriage return) والانتقال إلى سطر جديد (line feed)).
4. An optional body. A GET normally has none; a POST or PUT carries the new resource here.جسم اختياري. طلب GET عادةً بلا جسم؛ أما POST أو PUT فيحمل المورد الجديد هنا.

Two headers appear on the slide. Host: localhost names the server. It looks redundant, since the client already connected to that machine, but one machine often hosts many websites on one IP address, and Host tells it which one you mean. RFC 9112 makes it mandatory: a client must send Host, and a server must answer 400 Bad Request to an HTTP/1.1 request without it. Accept: text/html says what kind of content the client would like back, here an HTML page. A JSON API client would send Accept: application/json.

تظهر ترويستان في الشريحة. Host: localhost تسمّي الخادم. تبدو زائدة، لأن العميل اتصل بذلك الجهاز أصلًا، لكن جهازًا واحدًا كثيرًا ما يستضيف مواقع عديدة على عنوان IP واحد، وHost تخبره أيها تقصد. ويجعلها RFC 9112 إلزامية: يجب على العميل إرسال Host، ويجب على الخادم أن يرد بـ 400 Bad Request على أي طلب HTTP/1.1 يخلو منها. Accept: text/html تقول نوع المحتوى الذي يود العميل استلامه، وهو هنا صفحة HTML. وعميل API يتعامل بـ JSON سيرسل Accept: application/json.

Route and resource: the lecturer's vocabularyالمسار (route) والمورد (resource): مفردات المحاضر

Slide 11 labels the / as the "HTTP route (root)" and index.html as the "resource". Use those words in this course: the route is where on the server you are going, and the resource is the thing you get. In part 01 a Route was defined as a method plus a path, so GET together with /index.html is one route.

تسمّي الشريحة 11 الرمز / بـ "HTTP route (root)" وindex.html بـ "resource". استخدم هذه الكلمات في هذا المقرر: الـ route هو المكان الذي تذهب إليه على الخادم، والـ resource هو الشيء الذي تحصل عليه. في الجزء 01 عُرِّف الـ route على أنه طريقة زائد مسار، لذا فإن GET مع /index.html يشكّلان route واحدًا.

You can watch a real request yourself. The verbose flag of curl prints what it sends and receives:

يمكنك مشاهدة طلب حقيقي بنفسك. خيار الإسهاب (verbose) في curl يطبع ما يرسله وما يستقبله:

curl -v http://localhost/index.html
> GET /index.html HTTP/1.1
> Host: localhost
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: text/html
< Content-Length: 500
<
<html> ... </html>

The server found index.html. Its reply has the same shape as the request: a first line, header fields, an empty line, then the body. Only the first line is different.

وجد الخادم index.html. ورده له شكل الطلب نفسه: سطر أول، ثم حقول ترويسة، ثم سطر فارغ، ثم الجسم. السطر الأول وحده هو المختلف.

The status lineسطر الحالة (status line)

A response starts with a Status line: HTTP/1.1 200 OK. It has three parts: the version, the Status code 200, and the status message OK, which the standard calls the reason phrase. Programs act on the number; the phrase is for humans and clients should not rely on it.

تبدأ الاستجابة بـ status line: HTTP/1.1 200 OK. وله ثلاثة أجزاء: الإصدار، وstatus code وهو 200، ورسالة الحالة OK التي يسمّيها المعيار reason phrase. البرامج تتصرف بناءً على الرقم؛ أما العبارة فهي للبشر، ويجب ألا يعتمد عليها العملاء.

The first digit of the code is its class, and the class alone tells you who is responsible. RFC 9110 defines five, and every valid code lies between 100 and 599 (slide 24 returns to this range).

الرقم الأول من الرمز هو فئته، والفئة وحدها تخبرك من المسؤول. يعرّف RFC 9110 خمس فئات، وكل رمز صالح يقع بين 100 و599 (تعود الشريحة 24 إلى هذا النطاق).

A useful pairing with the CRUD table: a successful GET answers 200 OK, a successful POST usually answers 201 Created, and asking for a lamp that does not exist answers 404 Not Found.

ربط مفيد مع جدول CRUD: طلب GET الناجح يُرد عليه بـ 200 OK، وطلب POST الناجح يُرد عليه عادةً بـ 201 Created، وطلب مصباح غير موجود يُرد عليه بـ 404 Not Found.

The headers describe the bodyالترويسات تصف الجسم

The two response headers on slide 12 tell the client how to read what follows. The Content-Type header, text/html, says the body is an HTML page, so the browser renders it instead of showing raw text. The Content-Length header, 500, says the Message body is exactly 500 bytes long, so the client knows when it has received all of it.

ترويستا الاستجابة في الشريحة 12 تخبران العميل كيف يقرأ ما يليهما. ترويسة Content-Type، وقيمتها text/html، تقول إن الجسم صفحة HTML، فيعرضها المتصفح بدلًا من إظهار نص خام. وترويسة Content-Length، وقيمتها 500، تقول إن الـ message body طوله 500 bytes بالضبط، فيعرف العميل متى استلمه كله.

The empty line the slide leaves outالسطر الفارغ الذي تُغفله الشريحة

Slide 12 draws a gap between Header and Body but never says what is in the gap. It is an empty line: a CRLF with nothing before it. The receiver reads line by line, and the moment it meets an empty line it knows the header section has ended. Everything after it is body, and Content-Length tells it how many bytes of body to read.

ترسم الشريحة 12 فجوة بين Header وBody لكنها لا تقول أبدًا ما الذي في الفجوة. إنه سطر فارغ: CRLF لا يسبقه شيء. المستقبِل يقرأ سطرًا سطرًا، وفي اللحظة التي يصادف فيها سطرًا فارغًا يعرف أن قسم الترويسات انتهى. كل ما بعده جسم، وContent-Length تخبره كم بايتًا من الجسم عليه أن يقرأ.

Picture the house with four lamps. You send GET http://myHome.com/lamps and get back a list of all four. You send GET http://myHome.com/lamps/123 and get back the details of one lamp, the one whose ID is 123. Same method, same server, one extra path segment, and the answer changes from "everything" to "this one".

تخيّل منزلًا فيه أربعة مصابيح. ترسل GET http://myHome.com/lamps فتعود إليك قائمة بالمصابيح الأربعة كلها. وترسل GET http://myHome.com/lamps/123 فتعود إليك تفاصيل مصباح واحد، هو المصباح الذي رقمه (ID) 123. الـ method نفسها، والخادم نفسه، ومقطع واحد إضافي في المسار (path segment)، فيتغير الجواب من "كل شيء" إلى "هذا العنصر بالذات".

The two URLs are two different endpoints. The first is a collection endpoint: it names the set of lamps. The second is an item endpoint: it names one member of that set by its ID. Each lamp is a resource, and so is the collection itself. Microsoft's API design guidance states the same idea directly: a collection is a separate resource from the items inside it, so it gets its own URI, and items hang underneath it, as in /customers and /customers/5.

هذان الـ URL هما endpoints مختلفان. الأول collection endpoint: يسمّي مجموعة المصابيح. والثاني item endpoint: يسمّي عضوًا واحدًا من تلك المجموعة بواسطة الـ ID الخاص به. كل مصباح هو resource (مورد)، والمجموعة نفسها مورد أيضًا. وإرشادات Microsoft لتصميم الـ API تقول الفكرة نفسها مباشرة: المجموعة مورد منفصل عن العناصر التي بداخلها، لذلك لها URI خاص بها، والعناصر تتفرّع تحتها، كما في /customers و/customers/5.

One method, two meaningsmethod واحدة ومعنيان

Now run every HTTP method against both endpoints. The slide's point, in its own highlighted words, is to pay attention to how a method executed on an endpoint is interpreted. The verb stays fixed; the scope comes from the URL.

الآن طبّق كل HTTP method على الـ endpoint الاثنين. فكرة الشريحة، بكلماتها المظلّلة، هي أن تنتبه إلى كيف يُفسَّر تنفيذ method على endpoint معيّن. الفعل ثابت لا يتغير، أما النطاق (scope) فيأتي من الـ URL.

Read the rows one at a time. GET is a read in both columns; only the amount returned changes. PUT sets state: on the collection it is a bulk update (every lamp on, or every lamp at the same brightness), on the item it updates one lamp. Microsoft's conventions table has exactly this shape, listing PUT on a collection as a bulk update and PUT on an item as an update of that item. POST on the collection creates new members: when the hub discovers a lamp that was just screwed in, the server registers a virtual resource for it and assigns it an ID. That ID is then the last segment of the new lamp's item URL.

اقرأ الصفوف واحدًا واحدًا. GET قراءة في العمودين، والذي يتغير هو كمية ما يُعاد فقط. PUT تضبط الحالة: على المجموعة هي تحديث جماعي (bulk update)، أي تشغيل كل المصابيح أو جعلها كلها بالسطوع نفسه، وعلى العنصر تحدّث مصباحًا واحدًا. جدول الأعراف (conventions) عند Microsoft له هذا الشكل بالضبط، إذ يذكر PUT على المجموعة كتحديث جماعي، وPUT على العنصر كتحديث لذلك العنصر. وPOST على المجموعة تنشئ أعضاء جددًا: عندما يكتشف الـ hub مصباحًا رُكّب للتو، يسجّل الخادم له موردًا افتراضيًا (virtual resource) ويعيّن له ID. وهذا الـ ID يصبح بعد ذلك المقطع الأخير في رابط العنصر (item URL) الخاص بالمصباح الجديد.

Why DELETE means "disable" hereلماذا تعني DELETE هنا "تعطيل"

DELETE is the surprising row. A database row can be erased, but no request can remove a physical lamp from the ceiling. So this API interprets DELETE as switching the lamp's Enabled flag to false. The lamp still exists, still has ID 123, and can be enabled again later. Slide 23 makes this explicit: the response to DELETE carries {"id": 123, "Enabled": false}.

DELETE هو الصف المفاجئ. صف في قاعدة البيانات يمكن مسحه، لكن لا يوجد طلب يستطيع أن يزيل مصباحًا حقيقيًا من السقف. لذلك يفسّر هذا الـ API الـ DELETE على أنها تحويل علامة Enabled الخاصة بالمصباح إلى false. المصباح ما زال موجودًا، وما زال رقمه 123، ويمكن تفعيله مرة أخرى لاحقًا. والشريحة 23 تقول ذلك صراحة: الرد على DELETE يحمل {"id": 123, "Enabled": false}.

Suppose a clinic's booking system stores visits. Every operation anyone will ever ask for falls into one of a few shapes: see all visits, see one, book a new one, change one, cancel one. Write each shape as a route, a method plus a path, and you get the table below.

افترض أن نظام حجوزات في عيادة يخزّن الزيارات (visits). كل عملية سيطلبها أي شخص في أي وقت تقع في أحد أشكال قليلة: عرض كل الزيارات، عرض زيارة واحدة، حجز زيارة جديدة، تعديل زيارة، إلغاء زيارة. اكتب كل شكل منها على هيئة route (مسار)، أي method مع path، فتحصل على الجدول أدناه.

The :id in the path is a placeholder, not literal text. A router matches /visits/42 against /visits/:id and hands 42 to the handler as the ID. The table is nearly what Ruby on Rails generates from a single resources declaration: GET on the collection to list, GET on /new for a form, POST on the collection to create, and GET, PATCH or PUT, and DELETE on the item URL. Rails adds one route the slide leaves out, GET /visits/:id/edit for an edit form. Notice that three paths serve six valid routes here, because the router matches on the method and the path together.

الـ :id في المسار عنصر نائب (placeholder)، وليس نصًا حرفيًا. الـ router يطابق /visits/42 مع /visits/:id ويمرّر 42 إلى الـ handler على أنه الـ ID. هذا الجدول يكاد يكون ما يولّده Ruby on Rails من تعريف resources واحد: GET على المجموعة للعرض، وGET على /new لنموذج (form)، وPOST على المجموعة للإنشاء، ثم GET وPATCH أو PUT وDELETE على رابط العنصر. ويضيف Rails مسارًا واحدًا تتركه الشريحة، وهو GET /visits/:id/edit لنموذج التعديل. لاحظ أن ثلاثة مسارات (paths) فقط تخدم هنا ستة routes صحيحة، لأن الـ router يطابق على الـ method والـ path معًا.

The bad route: POST on an IDالمسار الخاطئ: POST على ID

The last row is the one the slide circles in red. Why is POST /visits/:id wrong? Think about who knows the ID. When a visit is created, it does not have an ID yet; the server assigns one. So creation must be addressed to something that already exists, and that is the collection. POST on /visits says "add a new member to this set and tell me its ID". RFC 9110 lists exactly this use of POST: creating a new resource that has yet to be identified by the origin server, with a 201 Created response whose Location header names the new resource.

الصف الأخير هو الذي تحيطه الشريحة بدائرة حمراء. لماذا POST /visits/:id خاطئ؟ فكّر في من يعرف الـ ID. عندما تُنشأ زيارة لا يكون لها ID بعد، والخادم هو من يعيّنه. لذلك يجب أن يوجَّه الإنشاء إلى شيء موجود مسبقًا، وهذا الشيء هو المجموعة. POST على /visits تقول "أضف عضوًا جديدًا إلى هذه المجموعة وأخبرني بالـ ID الخاص به". ويذكر RFC 9110 هذا الاستخدام لـ POST بالضبط: إنشاء مورد جديد لم يحدد له الخادم الأصلي (origin server) معرّفًا بعد، مع رد 201 Created يسمّي الـ Location header فيه المورد الجديد.

If you already have an ID, the visit already exists, and changing it is an update. The method for replacing the state of a resource at a known URL is PUT; RFC 9110 defines PUT as a request that the state of the target resource be created or replaced with the enclosed representation. The slide's note says the same in plain words: creating a new visit, but if an ID is provided, it should update instead. Microsoft's conventions table marks POST on /customers/1 simply as an error.

إذا كان لديك ID بالفعل، فالزيارة موجودة مسبقًا، وتغييرها تحديث. والـ method المخصصة لاستبدال حالة مورد على URL معروف هي PUT، إذ يعرّف RFC 9110 الـ PUT بأنها طلب بأن تُنشأ حالة المورد المستهدف أو تُستبدل بالتمثيل (representation) المرفق. وملاحظة الشريحة تقول الشيء نفسه بكلمات بسيطة: إنشاء زيارة جديدة، لكن إذا أُعطي ID فيجب أن يكون تحديثًا بدلًا من ذلك. وجدول الأعراف عند Microsoft يعلّم POST على /customers/1 ببساطة على أنه خطأ (error).

Here is a full URL from the lamp API: http://www.myhome.com/lamps/123?brightness=6&color=green. Read it left to right and every piece has a job. Some pieces get the request to the right machine, some pick the right handler, one picks the resource, and the tail carries the data the operation needs.

هذا URL كامل من الـ lamp API: http://www.myhome.com/lamps/123?brightness=6&color=green. اقرأه من اليسار إلى اليمين، وستجد أن لكل قطعة فيه وظيفة. بعض القطع توصل الطلب إلى الجهاز الصحيح، وبعضها يختار الـ handler الصحيح، وقطعة واحدة تختار المورد، والذيل يحمل البيانات التي تحتاجها العملية.

The standards use slightly different names for the same pieces. RFC 3986 splits every URI into scheme, authority, path, query and fragment, so www.myhome.com is the authority and /lamps/123 together is the path. The lecture splits the path in two because, for an API, the two halves do different work: /lamps picks the handler and /123 picks the resource inside it. Combined, /lamps/123 is the URI that identifies one lamp.

المعايير تستخدم أسماء مختلفة قليلًا للقطع نفسها. يقسّم RFC 3986 كل URI إلى scheme وauthority وpath وquery وfragment، لذلك www.myhome.com هو الـ authority، و/lamps/123 كله هو الـ path. والمحاضرة تقسّم الـ path إلى قسمين لأن النصفين في الـ API يؤديان عملين مختلفين: /lamps يختار الـ handler، و/123 يختار الـ resource داخله. ومعًا يكون /lamps/123 هو الـ URI الذي يعرّف مصباحًا واحدًا.

The query string: inputs, not identityالـ query string: مدخلات، وليست هوية

The query string starts at the first ?. After it come key=value pairs separated by &. So ?brightness=6&color=green carries two inputs, brightness = 6 and color = green. RFC 3986 notes that the query component is often used to carry information as key=value pairs, and MDN describes the parameters as a list of key/value pairs separated with the & symbol, which each server interprets by its own rules.

تبدأ الـ query string عند أول ?. وبعدها تأتي أزواج key=value تفصل بينها &. إذن ?brightness=6&color=green تحمل مدخلين: brightness = 6 وcolor = green. ويذكر RFC 3986 أن مكوّن الاستعلام (query component) يُستخدم كثيرًا لحمل المعلومات على هيئة أزواج key=value، ويصف MDN المعاملات (parameters) بأنها قائمة من أزواج key/value مفصولة بالرمز &، ويفسّرها كل خادم بقواعده الخاصة.

Slide 16 shows what happens on arrival. The server runs a program for resource /123, feeds it the two inputs, and the output is the new state of the lamp: brightness 6, color green. The slide's highlighted sentence is the takeaway: the inputs to the program are given explicitly in the URL.

تعرض الشريحة 16 ما يحدث عند الوصول. يشغّل الخادم برنامجًا للمورد /123، ويغذّيه بالمدخلين، والمخرج هو الحالة الجديدة للمصباح: السطوع 6 واللون أخضر. والجملة المظلّلة في الشريحة هي الخلاصة: مدخلات البرنامج تُعطى صراحة في الـ URL.

• The first ? starts the query; any later ? is just part of the query text.أول ? يبدأ الاستعلام، وأي ? يأتي بعده هو مجرد جزء من نص الاستعلام.
• & separates pairs; = separates a key from its value.& تفصل بين الأزواج، و= تفصل المفتاح (key) عن قيمته (value).
• Everything before the ? says where; everything after says with what.كل ما قبل ? يقول أين، وكل ما بعده يقول بماذا.

Picture two teams building a lamp API. One sends GET /getLampStatus?id=123 and POST /doSetBrightness, keeps a login session in server memory, and returns a different JSON shape from every endpoint. The other uses /lamps/123 for the lamp, changes it with standard methods, and puts everything the server needs into each request. Both speak HTTP. Only the second one is following REST.

تخيّل فريقين يبنيان واجهة API لمصباح. الفريق الأول يرسل GET /getLampStatus?id=123 وPOST /doSetBrightness، ويحتفظ بجلسة تسجيل الدخول في ذاكرة الخادم، ويعيد شكلًا مختلفًا منJSON من كل نقطة نهاية. والفريق الثاني يستخدم /lamps/123 للدلالة على المصباح، ويغيّره بالطرق القياسية، ويضع في كل طلب كل ما يحتاجه الخادم. كلا الفريقين يتحدث HTTP، لكن الثاني وحده يتبع REST.

The difference is not the protocol, which is the same, but the design discipline. REST stands for REpresentational State Transfer. Roy Thomas Fielding introduced it in his doctoral dissertation at the University of California, Irvine, in 2000, as a description of the principles that had guided the design of the Web itself.

الفرق ليس في البروتوكول (protocol)، فهو نفسه لدى الفريقين، بل في الانضباط التصميمي. REST اختصار لـ REpresentational State Transfer، أي "نقل الحالة التمثيلية". قدّمه Roy Thomas Fielding في أطروحة الدكتوراه الخاصة به في جامعة كاليفورنيا، إرفاين (University of California, Irvine) عام 2000، وصفًا للمبادئ التي وجّهت تصميم الويب نفسه.

REST is an architectural style: a named set of constraints on how the components of a system may interact. A protocol fixes message formats, field names and the order of exchanges. A style fixes none of that; it says things like "the server must not remember the client between requests" and leaves the bytes to whatever protocol you choose. REST then leverages HTTP to build scalable, stateless APIs, because HTTP already has what the constraints ask for: URLs to name resources, a fixed set of methods, status codes, caching headers and media types.

REST هو أسلوب معماري (architectural style): أي مجموعة مسمّاة من القيود على الطريقة التي يُسمح بها لمكونات النظام أن تتفاعل. البروتوكول يحدد صيغ الرسائل وأسماء الحقول وترتيب التبادلات. أما الأسلوب فلا يحدد شيئًا من ذلك، بل يقول أشياء مثل "يجب ألا يتذكر الخادم العميل بين طلب وآخر"، ويترك البايتات لأي بروتوكول تختاره. ثم يستفيد REST من HTTP لبناء واجهات API قابلة للتوسع وعديمة الحالة، لأن HTTP يملك أصلًا ما تطلبه هذه القيود: عناوين URL لتسمية الموارد، ومجموعة ثابتة من الطرق، ورموز الحالة، وترويسات التخزين المؤقت، وأنواع الوسائط (media types).

Statelessness, stated preciselyانعدام الحالة بتعريف دقيق

The slide singles out one constraint before listing the others, because it is the one most people get wrong. Statelessness has two halves, and an exam answer needs both:

تخصّ الشريحة قيدًا واحدًا بالذكر قبل سرد البقية، لأنه القيد الذي يخطئ فيه أكثر الناس. انعدام الحالة (Statelessness) له شقّان، وإجابة الاختبار تحتاج إلى الاثنين:

1. The server does not store client session data between requests.لا يخزّن الخادم بيانات جلسة العميل (session data) بين الطلبات.
2. Every request must contain all the information necessary to process it.يجب أن يحتوي كل طلب على كل المعلومات اللازمة لمعالجته.

The two halves are the same rule seen from each side. If the server keeps nothing, the request must bring everything: which lamp, who is asking, and what change is wanted. Note what the server is allowed to keep: the lamp's own state, its brightness and power, is resource state and lives on the server. What it may not keep is conversation state, such as "this client logged in five minutes ago and was looking at lamp 123".

الشقّان هما القاعدة نفسها منظورًا إليها من كل جانب. إذا كان الخادم لا يحتفظ بشيء، فيجب أن يحمل الطلب كل شيء: أي مصباح، ومن يسأل، وما التغيير المطلوب. لاحظ ما يُسمح للخادم بالاحتفاظ به: حالة المصباح نفسه، أي سطوعه وتشغيله، هي حالة المورد (resource state) وتعيش على الخادم. أما ما لا يجوز له الاحتفاظ به فهو حالة المحادثة (conversation state)، مثل "هذا العميل سجّل دخوله قبل خمس دقائق وكان ينظر إلى المصباح 123".

REST defines six architectural constraints: five mandatory and one optional. Fielding builds them up one at a time, each added constraint buying a property the Web needed. Here is the whole map before we walk through it; hover to see the lamp example on each card.

يعرّف REST ستة قيود معمارية (architectural constraints): خمسة إلزامية وواحد اختياري. يبنيها Fielding قيدًا بعد قيد، وكل قيد يُضاف يكسب خاصية كان الويب يحتاج إليها. إليك الخريطة كاملة قبل أن نمرّ عليها واحدًا واحدًا، ومرّر المؤشر لترى مثال المصباح على كل بطاقة.

1. Client-server: split the jobs1. العميل والخادم (Client-server): تقسيم المهام

A mobile app shows a slider and a power button. A server holds the truth about lamp 123: is it on, how bright is it. The app never touches the lamp directly; it asks the server through the REST API. That is the client-server constraint: separation of client and server responsibilities. The client owns the user interface, the server owns the data and its state.

تطبيق جوال يعرض شريط تمرير وزر تشغيل. والخادم يحتفظ بالحقيقة عن المصباح 123: هل هو مضاء، وكم سطوعه. التطبيق لا يلمس المصباح مباشرة أبدًا، بل يسأل الخادم عبر واجهة REST API. هذا هو قيد العميل والخادم (client-server constraint): الفصل بين مسؤوليات العميل ومسؤوليات الخادم. العميل يملك واجهة المستخدم، والخادم يملك البيانات وحالتها.

The payoff is independent evolution. You can ship an iPhone app, an Android app and a web dashboard against the same server, or rewrite the server in a new language, without changing the others, as long as the interface between them holds.

والمكسب هو التطور المستقل لكل طرف. يمكنك إطلاق تطبيق iPhone وتطبيق Android ولوحة تحكم على الويب تتعامل كلها مع الخادم نفسه، أو إعادة كتابة الخادم بلغة جديدة، دون تغيير البقية، ما دامت الواجهة بينهما ثابتة.

2. Statelessness: every request stands alone2. انعدام الحالة (Statelessness): كل طلب قائم بذاته

Now the app sends three requests in a row: read lamp 123, dim it to 80, read it again. Under statelessness each of those requests carries the lamp ID and the required authentication, and none of them relies on the request before it. The server answers each one as if it had never seen this client.

الآن يرسل التطبيق ثلاثة طلبات متتالية: اقرأ المصباح 123، ثم خفّض سطوعه إلى 80، ثم اقرأه مرة أخرى. في ظل انعدام الحالة يحمل كل طلب من هذه الطلبات معرّف المصباح والمصادقة المطلوبة، ولا يعتمد أي منها على الطلب الذي قبله. ويجيب الخادم عن كل طلب كأنه لم يرَ هذا العميل من قبل.

That is why the constraint exists. Fielding lists three gains: visibility (a monitor can understand a request by looking at that request alone), reliability (recovering from a partial failure is easy) and scalability (the server frees resources right after each request). In cloud terms the third one is the big one: if no server holds your session, a load balancer can send your next request to any of ten identical servers, and you scale by adding servers. The cost is that every request repeats some data, such as the token, which adds a few bytes to each message.

ولهذا وُجد هذا القيد. يذكر Fielding ثلاثة مكاسب: الوضوح (visibility)، إذ يستطيع نظام المراقبة فهم الطلب بالنظر إليه وحده؛ والموثوقية (reliability)، إذ يسهل التعافي من عطل جزئي؛ وقابلية التوسع (scalability)، إذ يحرر الخادم موارده فور انتهاء كل طلب. وبمصطلحات السحابة فإن المكسب الثالث هو الأهم: إذا لم يكن أي خادم يحتفظ بجلستك، يستطيع موازن الأحمال (load balancer) أن يرسل طلبك التالي إلى أي خادم من عشرة خوادم متطابقة، فتتوسع بإضافة خوادم. والثمن أن كل طلب يكرر بعض البيانات، مثل الرمز (token)، مما يضيف بضعة بايتات إلى كل رسالة.

3. Cacheability: let responses be reused3. قابلية التخزين المؤقت (Cacheability): اسمح بإعادة استخدام الاستجابات

Lamp status does not change every millisecond. If a dashboard refreshes every few seconds, sending each refresh all the way to the server is waste. Cacheability says that responses must indicate whether they can be cached and reused. In HTTP that label is the Cache-Control header. When the server returns Cache-Control: max-age=60, it allows the lamp information to be reused for 60 s. A response that must never be reused, such as a one-time token, says so with no-store.

حالة المصباح لا تتغير كل جزء من الثانية. فإذا كانت لوحة التحكم تتحدّث كل بضع ثوانٍ، فإن إرسال كل تحديث حتى الخادم هدر. تنص قابلية التخزين المؤقت (Cacheability) على أن الاستجابات يجب أن توضّح هل يمكن تخزينها مؤقتًا وإعادة استخدامها أم لا. وفي HTTP هذه العلامة هي الترويسة Cache-Control. فعندما يعيد الخادم Cache-Control: max-age=60، فهو يسمح بإعادة استخدام معلومات المصباح لمدة 60 s. والاستجابة التي يجب ألا يُعاد استخدامها أبدًا، مثل رمز يُستخدم مرة واحدة، تصرّح بذلك عبر no-store.

You want lamp 123 at 80 percent brightness. Under REST the app sends PATCH /lamps/123 with the header Content-Type: application/json and the body {"brightness": 80}. The response describes the lamp and includes links for what you can do next. That one exchange already demonstrates all four parts of the next constraint.

تريد أن يكون سطوع المصباح 123 عند 80 بالمئة. في REST يرسل التطبيق PATCH /lamps/123 مع الترويسة Content-Type: application/json والجسم {"brightness": 80}. وتصف الاستجابة المصباح وتتضمن روابط لما يمكنك فعله بعد ذلك. هذا التبادل الواحد يوضّح وحده الأجزاء الأربعة كلها للقيد التالي.

4. Uniform interface: one way to talk to every resource4. الواجهة الموحدة (Uniform interface): طريقة واحدة للتعامل مع كل مورد

The uniform interface means standardized interaction with resources. Every resource is handled with the same small set of moves, so a client that knows how to talk to lamps also knows how to talk to users or thermostats. It has four sub-constraints:

الواجهة الموحدة (uniform interface) تعني تفاعلًا موحدًا قياسيًا مع الموارد. يُتعامل مع كل مورد بالمجموعة الصغيرة نفسها من الحركات، فالعميل الذي يعرف كيف يتعامل مع المصابيح يعرف أيضًا كيف يتعامل مع المستخدمين أو منظمات الحرارة. ولها أربعة قيود فرعية:

1. Resource identification through URIs. Each resource has a URI: /lamps/123 uniquely identifies lamp 123.تعريف الموارد عبر عناوين URI. لكل مورد (resource) عنوان URI: فالعنوان /lamps/123 يعرّف المصباح 123 تعريفًا فريدًا.
2. Manipulation through representations. The client never touches the lamp object; it sends a representation of the desired state. PATCH /lamps/123 with {"brightness": 80} updates the brightness. PATCH applies a partial change, unlike PUT which replaces the whole resource.التعديل عبر التمثيلات. العميل لا يلمس كائن المصباح أبدًا، بل يرسل تمثيلًا (representation) للحالة المرغوبة. فالطلب PATCH /lamps/123 مع {"brightness": 80} يحدّث السطوع. والطريقة PATCH تطبّق تغييرًا جزئيًا، بخلاف PUT التي تستبدل المورد كاملًا.
3. Self-descriptive messages. Each message carries enough to be understood alone. The method PATCH, the header Content-Type: application/json and the JSON body together describe the requested update; that is a self-descriptive message.رسائل تصف نفسها بنفسها. كل رسالة تحمل ما يكفي لفهمها وحدها. فالطريقة PATCH، والترويسة Content-Type: application/json، وجسم JSON، تصف معًا التحديث المطلوب؛ وهذه هي الرسالة ذاتية الوصف (self-descriptive message).
4. Hypermedia as the engine of application state (HATEOAS). The lamp's response includes links or actions to retrieve, update or delete the lamp, so the client discovers what it can do next from the response instead of from hard-coded URLs.الوسائط التشعبية بوصفها محرّك حالة التطبيق (HATEOAS). تتضمن استجابة المصباح روابط أو إجراءات لجلب المصباح أو تحديثه أو حذفه، فيكتشف العميل ما يمكنه فعله بعد ذلك من الاستجابة نفسها بدلًا من عناوين URL مكتوبة مسبقًا في الشيفرة.

5. Layered system: the client sees only the next hop5. النظام الطبقي (Layered system): العميل لا يرى إلا الطبقة التالية

A lamp request rarely goes straight to one server. It passes through an API gateway that checks the token and rate limits, then a load balancer that picks a healthy server, before reaching the smart-home servers. A layered system supports such intermediary layers, including proxies, gateways and load balancers. In Fielding's words, each component cannot see beyond the immediate layer it is interacting with.

نادرًا ما يذهب طلب المصباح مباشرة إلى خادم واحد. فهو يمر عبر بوابة API (API gateway) تتحقق من الرمز وتطبّق حدود معدّل الطلبات (rate limits)، ثم عبر موازن أحمال يختار خادمًا سليمًا، قبل أن يصل إلى خوادم المنزل الذكي. والنظام الطبقي (layered system) يدعم مثل هذه الطبقات الوسيطة، ومنها الخوادم الوسيطة (proxies) والبوابات وموازنات الأحمال. وبتعبير Fielding: لا يستطيع أي مكوّن أن يرى ما وراء الطبقة المباشرة التي يتفاعل معها.

This is where the constraints reinforce each other. Because requests are stateless, the load balancer can send each one anywhere. Because messages are self-descriptive and cacheable, a proxy in the middle can cache them without knowing anything about lamps. For the edge-to-cloud continuum this matters directly: a cache or gateway at the edge is just another layer the client never has to know about.

هنا تعزّز القيود بعضها بعضًا. فلأن الطلبات عديمة الحالة، يستطيع موازن الأحمال أن يرسل كل طلب إلى أي مكان. ولأن الرسائل ذاتية الوصف وقابلة للتخزين المؤقت، يستطيع خادم وسيط في المنتصف أن يخزنها مؤقتًا دون أن يعرف أي شيء عن المصابيح. وهذا يهم مباشرة في سلسلة الحافة إلى السحابة (edge-to-cloud continuum): فالذاكرة المؤقتة أو البوابة الموجودة على الحافة (edge) ما هي إلا طبقة أخرى لا يحتاج العميل أبدًا إلى معرفتها.

6. Code on demand: the optional one6. الشيفرة عند الطلب (Code on demand): القيد الاختياري

The server sends JavaScript to the browser to provide an interactive lamp-control interface. That is code on demand: servers may provide executable code to clients, extending what the client can do after it is deployed. It is the only optional constraint, because it reduces visibility: an intermediary cannot easily tell what downloaded code will do.

يرسل الخادم شيفرة JavaScript إلى المتصفح ليقدّم واجهة تفاعلية للتحكم في المصباح. هذه هي الشيفرة عند الطلب (code on demand): يجوز للخوادم أن تزوّد العملاء بشيفرة قابلة للتنفيذ، فتوسّع ما يستطيع العميل فعله بعد نشره. وهي القيد الاختياري الوحيد، لأنها تقلل الوضوح (visibility): إذ لا يستطيع الوسيط أن يعرف بسهولة ما ستفعله الشيفرة التي جرى تنزيلها.

The constraints say what a REST API must respect. The slides then switch to practice: what you actually write down when designing one. Take "dim lamp 123 to 80" one last time and list every decision you had to make.

تحدد القيود ما يجب أن تلتزم به واجهة REST API. ثم تنتقل الشرائح إلى التطبيق العملي: ما الذي تكتبه فعلًا عندما تصمم واجهة كهذه. خذ "خفّض سطوع المصباح 123 إلى 80" مرة أخيرة، واسرد كل قرار كان عليك اتخاذه.

Those five rows are the REST design elements: URL, HTTP request method, HTTP response status code, header fields and JSON message. The next part uses exactly this list to design the full lamp API and a calculator API, so learn it now as a checklist.

هذه الصفوف الخمسة هي عناصر تصميم REST (REST design elements): URL، وطريقة طلب HTTP، ورمز حالة استجابة HTTP، وحقول الترويسة، ورسالة JSON. يستخدم الجزء التالي هذه القائمة بالضبط لتصميم واجهة المصباح كاملة وواجهة آلة حاسبة، لذا احفظها الآن كقائمة تحقق.

How the pieces map onto the constraintsكيف ترتبط هذه الأجزاء بالقيود

Every entity the system manages, whether a file, a user, a virtual machine or an IoT device, is treated as a resource, and each resource is uniquely identified by a URI such as /lamps/123. That is design element 1 and uniform-interface sub-constraint i.

كل كيان يديره النظام، سواء كان ملفًا أو مستخدمًا أو آلة افتراضية أو جهاز إنترنت أشياء (IoT)، يُعامل على أنه مورد (resource)، وكل مورد يُعرَّف تعريفًا فريدًا بعنوان URI مثل /lamps/123. هذا هو عنصر التصميم 1 والقيد الفرعي i للواجهة الموحدة.

A resource is represented in JSON, the format most REST APIs use. JSON represents resource data as key-value pairs, and those representations are exchanged in HTTP request and response bodies. That is design element 5 and sub-constraint ii. Its media type is application/json.

يُمثَّل المورد بصيغة JSON، وهي الصيغة التي تستخدمها معظم واجهات REST. تمثّل JSON بيانات المورد على شكل أزواج مفتاح وقيمة (key-value pairs)، وتُتبادل هذه التمثيلات داخل أجسام (bodies) طلبات HTTP واستجاباته. هذا هو عنصر التصميم 5 والقيد الفرعي ii. ونوع الوسائط الخاص بها هو application/json.

Additional information travels in header fields: an authentication token, the Content-Type of the body, and the response formats the client accepts (Accept). That is design element 4, and it is what makes messages self-descriptive.

تنتقل المعلومات الإضافية في حقول الترويسة (header fields): رمز المصادقة (authentication token)، وContent-Type الخاص بالجسم، وصيغ الاستجابة التي يقبلها العميل (Accept). هذا هو عنصر التصميم 4، وهو ما يجعل الرسائل ذاتية الوصف.

Finally, REST APIs follow stateless communication: each request contains the information the server needs to process it independently. That is why the token sits in a header of every request instead of in a server-side session.

وأخيرًا، تتبع واجهات REST تواصلًا عديم الحالة: كل طلب يحتوي على المعلومات التي يحتاجها الخادم لمعالجته باستقلال. ولهذا يوضع الرمز في ترويسة كل طلب بدلًا من حفظه في جلسة على جانب الخادم.

You are on the sofa with your phone. The browser shows a page at .../lamps/123 with an ON button, an OFF button and an intensity slider. You tap ON. A second later the lamp in the hallway lights up. What happened in between is the whole subject of this lecture in miniature.

أنت جالس على الأريكة وفي يدك هاتفك. يعرض المتصفح صفحة على .../lamps/123 فيها زر ON وزر OFF ومنزلق لشدة الإضاءة. تضغط ON. وبعد ثانية يضيء المصباح في الممر. ما حدث بين الضغطة والإضاءة هو موضوع هذه المحاضرة كله في صورة مصغّرة.

Three components, two very different links. Between the browser and the Raspberry Pi the link is HTTP: the browser is an HTTP client, the Pi runs an HTTP server, and the tap becomes a request to an Endpoint. Between the Pi and the lamp the link is a device signal, a GPIO pin, a relay or a radio protocol, that the web never sees. The API is the HTTP side only. That is why the design problem is phrased in terms of URLs and methods and never mentions wires or voltages.

ثلاثة مكونات، ورابطان مختلفان تمامًا. بين المتصفح وRaspberry Pi الرابط هو HTTP: المتصفح هو HTTP client، والـ Pi يشغّل HTTP server، والضغطة تصبح طلبًا إلى endpoint. أما بين الـ Pi والمصباح فالرابط إشارة جهاز: منفذ GPIO، أو مُرحِّل (relay)، أو بروتوكول لاسلكي، ولا يراه الويب أبدًا. الـ API هو جانب HTTP فقط. ولهذا تُصاغ مسألة التصميم بلغة عناوين URL والطرق، ولا تذكر الأسلاك أو الجهد الكهربائي أبدًا.

The lamp is the Resource: the thing the server manages and exposes. The number 123 is its identity, and the URL that names it, /lamps/123, is its URI. Every operation the UI offers is a change to the lamp's state: whether it is on, how bright it is, whether it is enabled at all. So the design question becomes: which method on which URL changes which part of that state, and what does the data look like?

المصباح هو resource (المورد): الشيء الذي يديره الخادم ويعرضه. الرقم 123 هو هويته، والعنوان الذي يسمّيه، /lamps/123، هو URI الخاص به. كل عملية تقدمها الواجهة هي تغيير في حالة المصباح: هل هو مضاء، وما درجة سطوعه، وهل هو مفعَّل أصلًا. فيصبح سؤال التصميم: أي طريقة على أي URL تغيّر أي جزء من هذه الحالة، وكيف تبدو البيانات؟

Start with one row. A GET request to http://myHome.com/lamps/123 returns {"id": 123, "Enabled": true, "ON": true, "brightness": 35}. Read the JSON as a sentence: lamp 123 is enabled, switched on, and at 35 percent brightness. That JSON is a Representation of the lamp's state, not the lamp itself.

ابدأ بصف واحد. طلب GET إلى http://myHome.com/lamps/123 يعيد {"id": 123, "Enabled": true, "ON": true, "brightness": 35}. اقرأ الـ JSON كجملة: المصباح 123 مفعَّل، ومضاء، وسطوعه 35 بالمئة. هذا الـ JSON هو representation (تمثيل) لحالة المصباح، وليس المصباح نفسه.

Now fill in the whole grid. The rows are the four methods. The columns are two URLs: the Collection endpoint /lamps, meaning all lamps, and the Item endpoint /lamps/123, meaning one lamp. Each cell says what that method does to that URL.

الآن املأ الشبكة كلها. الصفوف هي الطرق الأربع. والأعمدة عنوانان: collection endpoint /lamps ومعناها كل المصابيح، وitem endpoint /lamps/123 ومعناها مصباح واحد. كل خلية تقول ماذا تفعل تلك الطريقة بذلك العنوان.

Reading the table row by rowقراءة الجدول صفًا صفًا

• GET reads and never changes anything. On /lamps it lists every lamp; on /lamps/123 it returns one lamp's state.GET يقرأ ولا يغيّر أي شيء أبدًا. على /lamps يعرض قائمة بكل المصابيح، وعلى /lamps/123 يعيد حالة مصباح واحد.
• DELETE here means disable. The response {"id": 123, "Enabled": false} shows the lamp still exists, with its Enabled flag cleared. This is a soft delete: the record stays, so a PUT can enable the lamp again later. A physical lamp still screwed into the ceiling should not vanish from the system.DELETE هنا تعني التعطيل. الاستجابة {"id": 123, "Enabled": false} تُظهر أن المصباح ما زال موجودًا، مع إلغاء علامة Enabled. هذا حذف ناعم (soft delete): يبقى السجل، فيمكن لطلب PUT أن يعيد تفعيل المصباح لاحقًا. فالمصباح الحقيقي الذي ما زال مثبتًا في السقف لا ينبغي أن يختفي من النظام.
• PUT sends the full new state in the request: {"id": 123, "Enabled": true, "ON": true, "brightness": 60}. Compared with the GET above, only brightness changed, from 35 to 60. Sending every field is what makes PUT a replacement, and why it is Idempotent method: sending the same body twice leaves the lamp at 60 both times.PUT يرسل الحالة الجديدة كاملة في الطلب: {"id": 123, "Enabled": true, "ON": true, "brightness": 60}. مقارنةً بـ GET أعلاه، لم يتغير إلا السطوع، من 35 إلى 60. إرسال كل الحقول هو ما يجعل PUT عملية استبدال، ولهذا هو idempotent: إرسال الجسم نفسه مرتين يترك المصباح على 60 في المرتين.
• POST on /lamps asks the server to discover a newly installed lamp, assign it an ID and create its virtual resource. The response {"id": 123, "Enabled": true, "ON": false, "brightness": 0} carries the ID the server chose, and the new lamp starts off at zero brightness.POST على /lamps يطلب من الخادم أن يكتشف مصباحًا رُكِّب حديثًا، ويعطيه معرّفًا (ID)، وينشئ مورده الافتراضي. الاستجابة {"id": 123, "Enabled": true, "ON": false, "brightness": 0} تحمل المعرّف الذي اختاره الخادم، ويبدأ المصباح الجديد مطفأً بسطوع صفر.
• POST on /lamps/123 is not applicable. Creating something at an ID that already names an existing lamp is contradictory: the client cannot pick the ID, and lamp 123 already exists.POST على /lamps/123 غير قابل للتطبيق. إنشاء شيء عند معرّف يسمّي أصلًا مصباحًا موجودًا أمر متناقض: العميل لا يستطيع اختيار المعرّف، والمصباح 123 موجود بالفعل.

The Header fields column is the same for every row: a Cookie, an Authentication token and an Authorization token. They do not change the operation; they tell the server who is asking and whether they may. You would not want a neighbour on the same Wi-Fi to switch off your lamps.

عمود header fields هو نفسه في كل صف: Cookie، وauthentication token، وauthorization token. هذه لا تغيّر العملية، بل تخبر الخادم من الذي يطلب وهل يُسمح له. فأنت لا تريد أن يطفئ جارك المتصل بشبكة Wi-Fi نفسها مصابيحك.

Take one cell of the lamp table, "change the brightness of lamp 123", and ask what a developer needs to implement it. Which URL? Which method? What comes back if it works or fails? What metadata travels with it? What does the data look like? Those five questions are the REST design elements.

خذ خلية واحدة من جدول المصباح، "تغيير سطوع المصباح 123"، واسأل ماذا يحتاج المطوّر لتنفيذها. أي URL؟ أي طريقة؟ ماذا يعود إذا نجحت أو فشلت؟ ما البيانات الوصفية التي ترافقها؟ كيف تبدو البيانات؟ هذه الأسئلة الخمسة هي REST design elements (عناصر تصميم REST).

The URL names the resource: a domain name, which locates the server, plus a path, which locates the resource on it. The HTTP method names the operation. The Status code reports the outcome with a three-digit number. The header fields carry metadata about the message rather than the resource, such as cookies, tokens and Content-Type. The JSON message carries the resource representation itself: either its current state, in a response, or the change you want, in a request.

الـ URL يسمّي المورد: اسم نطاق (domain) يحدد مكان الخادم، ومسار (path) يحدد مكان المورد عليه. وHTTP method تسمّي العملية. وstatus code يبلّغ عن النتيجة برقم من ثلاث خانات. وحقول الترويسة تحمل بيانات وصفية عن الرسالة وليس عن المورد، مثل ملفات تعريف الارتباط (cookies) والرموز (tokens) وContent-Type. ورسالة JSON تحمل تمثيل المورد نفسه: إما حالته الحالية في الاستجابة، أو التغيير الذي تريده في الطلب.

Status codes: the first digit is the classرموز الحالة: الخانة الأولى هي الفئة

RFC 9110 states that all valid status codes lie between 100 and 599 inclusive, and that only the first digit carries a category. The last two digits pick a specific meaning inside the class. When you design an API, you are mostly choosing which 2xx, 4xx and 5xx codes it can return.

ينص RFC 9110 على أن كل رموز الحالة الصالحة تقع بين 100 و599 شاملةً، وأن الخانة الأولى وحدها تحمل الفئة. أما الخانتان الأخيرتان فتختاران معنى محددًا داخل الفئة. عندما تصمم API، فأنت في الغالب تختار أي رموز 2xx و4xx و5xx يمكن أن يعيدها.

The second example is a web page titled "My Awesome Calculator!". It has a box for X, a box for Y, four radio buttons (addition, subtraction, multiplication, division) and a Submit button. The task: design a REST API for the addition operation, so that the sum is computed on the server, not in the browser.

المثال الثاني صفحة ويب عنوانها "My Awesome Calculator!". فيها خانة لـ X، وخانة لـ Y، وأربعة أزرار اختيار (جمع، طرح، ضرب، قسمة)، وزر Submit. المهمة: صمّم REST API لعملية الجمع، بحيث يُحسب المجموع على الخادم وليس في المتصفح.

Work through the five elements in order. The URL needs a domain and a path, so the slide picks http://calculator.com/add. Adding two numbers reads data and changes nothing, so the method is GET. The inputs travel as JSON, {"X": 1, "Y": 2}. The caller must be allowed to use the service, so the request carries an Authorization header. Finally, list the status codes that the server can return.

مرّ على العناصر الخمسة بالترتيب. الـ URL يحتاج نطاقًا ومسارًا، فتختار الشريحة http://calculator.com/add. جمع عددين يقرأ بيانات ولا يغيّر شيئًا، فالطريقة هي GET. المدخلات تنتقل بصيغة JSON، {"X": 1, "Y": 2}. يجب أن يكون المستدعي مسموحًا له باستخدام الخدمة، لذلك يحمل الطلب ترويسة Authorization. وأخيرًا، اذكر رموز الحالة التي يمكن أن يعيدها الخادم.

On the server, the request is unpacked into a small environment: X = 1, Y = 2, op = Addition. The handler then runs Resp.send(X op Y) and the client receives 3. The browser never adds anything; it only sends inputs and displays an answer. This is the client-server split from Lecture 1: the computation lives behind the API.

على الخادم، يُفكّ الطلب إلى بيئة صغيرة: X = 1، Y = 2، op = Addition. ثم يشغّل المعالج Resp.send(X op Y) ويستقبل العميل 3. المتصفح لا يجمع أي شيء، بل يرسل المدخلات ويعرض الإجابة فقط. هذا هو الفصل بين العميل والخادم (client-server) من المحاضرة 1: الحساب يعيش خلف الـ API.

Each status code, with the request that triggers itكل رمز حالة مع الطلب الذي يسببه

A list of codes is easy to memorise and easy to confuse. Tie each to a concrete calculator request instead. The question to ask every time is: whose fault is it? A 4xx says the client must change the request. A 5xx says the request was fine and the server failed.

قائمة الرموز سهلة الحفظ وسهلة الخلط. لذلك اربط كل رمز بطلب محدد للآلة الحاسبة. والسؤال الذي تطرحه كل مرة: خطأ من هذا؟ الرمز 4xx يقول إن على العميل أن يغيّر الطلب. والرمز 5xx يقول إن الطلب كان سليمًا والخادم هو الذي فشل.

406 is the subtle one. It is about the response format. The client's Accept header lists the media types it can read. If the client says it will only take application/xml and the calculator only speaks JSON, the server cannot produce an acceptable answer. MDN notes that sending a default format with 200 may be preferable to a 406, so using it is a design choice: strict servers use it, lenient ones ignore the mismatch.

الرمز 406 هو الأدق. إنه يتعلق بصيغة الاستجابة. ترويسة Accept لدى العميل تسرد أنواع الوسائط (media types) التي يستطيع قراءتها. إذا قال العميل إنه لن يقبل إلا application/xml والآلة الحاسبة لا تتكلم إلا JSON، فلا يستطيع الخادم إنتاج إجابة مقبولة. وتشير MDN إلى أن إرسال صيغة افتراضية مع 200 قد يكون أفضل من 406، فاستخدامه قرار تصميمي: الخوادم الصارمة تستخدمه، والمتساهلة تتجاهل عدم التطابق.

Why the slide's GET with a body is shakyلماذا يُعد GET مع جسم في الشريحة تصميمًا مهزوزًا

The slide pairs GET with a JSON body. RFC 9110 is explicit that content received in a GET request has no generally defined semantics, cannot change the meaning of the request, and may cause some implementations to reject the request. A client should not send one unless the origin server has said it will support it. In practice, the browser's fetch throws an error if you give a GET request a body, and caches key stored responses on the method and URL, never the body, so two different sums sent to the same URL could collide in a cache.

تجمع الشريحة بين GET وجسم JSON. يصرّح RFC 9110 بأن المحتوى المستلَم في طلب GET ليس له دلالة معرّفة بشكل عام، ولا يمكنه تغيير معنى الطلب، وقد يجعل بعض التطبيقات ترفض الطلب. ولا ينبغي للعميل أن يرسله ما لم يعلن الخادم الأصلي أنه يدعمه. وعمليًا، دالة fetch في المتصفح ترمي خطأ إذا أعطيت طلب GET جسمًا، والذاكرات المؤقتة (caches) تفهرس الاستجابات المخزنة حسب الطريقة والـ URL وليس حسب الجسم أبدًا، لذلك قد يتصادم مجموعان مختلفان أُرسلا إلى الـ URL نفسه داخل الذاكرة المؤقتة.

Try every case in the builder. Start with the slide's design and the answer 3. Switch Accept to XML and watch the 406. Clear X, or type abc, for a 400. Mark the server as buggy or overloaded for 500 and 503. Then switch to GET with a query string and to POST and see how the request line and headers change while the five elements stay the same.

جرّب كل حالة في أداة البناء. ابدأ بتصميم الشريحة والإجابة 3. غيّر Accept إلى XML وشاهد 406. امسح X، أو اكتب abc، لتحصل على 400. اجعل الخادم معطوبًا أو محمّلًا فوق طاقته لتحصل على 500 و503. ثم انتقل إلى GET مع سلسلة استعلام وإلى POST، وشاهد كيف يتغير سطر الطلب والترويسات بينما تبقى العناصر الخمسة كما هي.

GET /add HTTP/1.1
Host: calculator.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.demo
Content-Type: application/json
Content-Length: 13

{"X":1,"Y":2}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12

{"result":3}

The slide designs addition and stops. The natural exam follow-up is: design the same API for subtraction, multiplication or division. The good news is that four of the five elements barely change. The path names the new operation, and the JSON carries new numbers. Division adds one new failure case.

تصمم الشريحة عملية الجمع وتتوقف. والسؤال الطبيعي التالي في الامتحان: صمّم الـ API نفسه للطرح أو الضرب أو القسمة. والخبر الجيد أن أربعة من العناصر الخمسة بالكاد تتغير. المسار يسمّي العملية الجديدة، والـ JSON يحمل أعدادًا جديدة. والقسمة تضيف حالة فشل جديدة واحدة.

The slide closes with references. The deck cites Henry Cocos's Cloud Computing lecture series (summer term 2025), four cloud textbooks and uptime.is, an availability calculator from Lecture 2 that this lecture does not use. They appear under Sources below, next to the standards that back the status code and GET claims in this part.

تُختَم الشريحة بالمراجع. يستشهد العرض بسلسلة محاضرات Cloud Computing لـ Henry Cocos (الفصل الصيفي 2025)، وأربعة كتب في الحوسبة السحابية، وuptime.is، وهي حاسبة توافر (availability) من المحاضرة 2 لا تستخدمها هذه المحاضرة. تظهر كلها تحت المصادر أدناه، بجانب المعايير التي تدعم ادعاءات رموز الحالة وGET في هذا الجزء.