Designing REST APIs: the lamp system and the calculatorتصميم واجهات REST API: نظام المصباح والآلة الحاسبة

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 في هذا الجزء.