Lecture 03 · Application Programming Interfaces

المحاضرة 03 · واجهات برمجة التطبيقات

Smart home API: collection vs item, routes table, query strings

API المنزل الذكي: المجموعة مقابل العنصر، وجدول المسارات، ونصوص الاستعلام

Slides 13–16الشرائح 13–16 P1 MUST

The same method means different things on /lamps and on /lamps/123. Learn to read the path first, then the method, then the query string.

الـ method نفسه يعني أشياء مختلفة على /lamps وعلى /lamps/123. تعلّم أن تقرأ المسار أولاً، ثم الـ method، ثم الـ query string.

Collection vs item: the path decides the scope

المجموعة مقابل العنصر: المسار يحدد النطاق

Slide 13 puts two endpoints side by side: http://myHome.com/lamps (the collection of all lamps) and http://myHome.com/lamps/123 (one item, the lamp with ID 123). The slide's warning: pay attention to how the execution of an HTTP method on an endpoint is interpreted. The endpoint structure decides whether you affect all lamps or one.

تضع الشريحة 13 endpoint بجانب آخر: http://myHome.com/lamps وهو الـ collection أي كل المصابيح، وhttp://myHome.com/lamps/123 وهو item واحد، أي المصباح ذو المعرّف 123. وتحذير الشريحة: انتبه لكيفية تفسير تنفيذ HTTP method على endpoint. فبنية الـ endpoint هي التي تحدد هل تؤثر على كل المصابيح أم على مصباح واحد.

Methodالـ Method/lamps (collection)/lamps (مجموعة collection)/lamps/123 (item)/lamps/123 (عنصر item)
GETlist all lamps in the houseعرض قائمة بكل المصابيح في المنزلget information about lamp 123جلب معلومات المصباح 123
DELETEdisable all lampsتعطيل كل المصابيحdisable lamp 123تعطيل المصباح 123
PUTturn all lamps on/off; change brightness of all lampsتشغيل كل المصابيح أو إطفاؤها، وتغيير سطوع كل المصابيحturn lamp 123 on/off; change its brightnessتشغيل المصباح 123 أو إطفاؤه، وتغيير سطوعه
POSTcreate virtual resources (lamps) with IDs for newly discovered lampsإنشاء resources افتراضية (مصابيح) لها معرّفات IDs للمصابيح المكتشفة حديثاًcreate a new virtual resource (lamp) with ID = 123إنشاء resource افتراضي جديد (مصباح) معرّفه ID = 123

اقرأ الجدول عمودياً: كل صف هو method واحد، والعمودان يختلفان فقط في النطاق. GET على الـ collection يسرد كل المصابيح، وعلى الـ item يُرجع معلومات مصباح واحد. DELETE يعطّل الكل أو واحداً. PUT يشغّل أو يطفئ أو يغيّر السطوع للكل أو لواحد. وPOST على /lamps يُنشئ virtual resources بمعرّفات للمصابيح المكتشفة حديثاً.

Note DELETE here means disable: the physical lamp does not vanish, but its virtual resource on the server is removed, so the API no longer manages it.

لاحظ أن DELETE هنا معناه التعطيل: المصباح الفعلي لا يختفي، لكن الـ virtual resource الخاص به على الخادم يُزال، فلا يعود الـ API يديره.

SAME METHOD, DIFFERENT SCOPE PUT /lamps 101 102 123 150 every lamp in the house changes collection PUT /lamps/123 101 102 123 150 only lamp 123 changes item
Swap PUT for GET or DELETE and the picture is the same: the trailing ID narrows the operation from every lamp to one.
ضع GET أو DELETE مكان PUT وتبقى الصورة نفسها: المعرّف في آخر المسار يضيّق العملية من كل المصابيح إلى مصباح واحد.

The visits routes table (slide 14)

جدول مسارات الزيارات (الشريحة 14)

Slide 14 lists the full conventional route set for a collection, using visit requests as the resource. :id is a placeholder: a real request puts a number there, such as /visits/7.

تسرد الشريحة 14 مجموعة الـ routes المعتادة كاملة لأي collection، باستخدام طلبات الزيارة كـ resource. و:id مجرد مكان محجوز، والطلب الحقيقي يضع رقماً مكانه مثل /visits/7.

Endpointالـ EndpointVerbالفعل (Verb)PurposeالغرضCRUD
/visitsGETlist all visitsعرض قائمة بكل الزياراتRead (collection)قراءة Read (مجموعة)
/visits/newGETshow the new-visit request formعرض نموذج طلب زيارة جديدةRead (a form page, nothing created yet)قراءة Read (صفحة نموذج، لم يُنشأ شيء بعد)
/visitsPOSTcreate a new visit, then redirect somewhereإنشاء زيارة جديدة، ثم إعادة التوجيه إلى مكان ماCreateإنشاء (Create)
/visits/:idGETshow info about one visitعرض معلومات زيارة واحدةRead (item)قراءة Read (عنصر)
/visits/:idPUTupdate one visitتحديث زيارة واحدةUpdateتحديث (Update)
/visits/:idDELETEdelete one visitحذف زيارة واحدةDeleteحذف (Delete)
/visits/:idPOSTError: cannot overwrite a visit. Do not do this.خطأ: لا يمكن الكتابة فوق زيارة. لا تفعل هذا.noneلا شيء

ستة routes صحيحة وواحد خاطئ. على الـ collection: GET /visits للسرد وPOST /visits للإنشاء. وGET /visits/new يعرض نموذج الطلب فقط ولا يُنشئ شيئاً. وعلى الـ item: GET للعرض وPUT للتحديث وDELETE للحذف. أما POST /visits/:id فهو خطأ.

Why is POST /visits/:id an error? The slide's note: "Creating a new visit, but if an ID is provided, it should update instead." POST means create, and creating goes to the collection where the server assigns the new ID. If you already have an ID, the visit already exists, so the operation you want is an update, and update is PUT.

لماذا POST /visits/:id خطأ؟ ملاحظة الشريحة: "Creating a new visit, but if an ID is provided, it should update instead." أي أن POST معناه الإنشاء، والإنشاء يذهب إلى الـ collection حيث يعيّن الخادم المعرّف الجديد. فإذا كان معك معرّف فالزيارة موجودة أصلاً، والعملية التي تريدها هي التحديث، والتحديث هو PUT.

Slide 13 vs slide 14الشريحة 13 مقابل الشريحة 14

Slide 13's lamp table does list POST /lamps/123 as "create a new virtual resource with ID = 123", while slide 14 marks POST /visits/:id as an error. If a question quotes the lamp table, answer from the lamp table. If it asks for the rule or the correct design, use slide 14: create with POST on the collection, and use PUT when the ID is already known.

جدول المصابيح في الشريحة 13 يذكر فعلاً POST /lamps/123 بمعنى "إنشاء virtual resource جديد بالمعرّف 123"، بينما تعتبر الشريحة 14 أن POST /visits/:id خطأ. إذا اقتبس السؤال جدول المصابيح فأجب منه. وإذا سأل عن القاعدة أو التصميم الصحيح فاعتمد الشريحة 14: الإنشاء بـ POST على الـ collection، وPUT عندما يكون المعرّف معروفاً.

Reading a URL with a query string (slides 15 and 16)

قراءة URL فيه نص استعلام query string (الشريحتان 15 و16)

http://www.myhome.com/lamps/123?brightness=6&color=green

FOUR PARTS, FOUR JOBS http:// www.myhome.com /lamps /123 ?brightness=6&color=green server route where to deliver resource operated on query string input to the operation brightness = 6 color = green HTTP Method (Resource: /123) new state for resource 123 "Run a program on the server with inputs brightness = 6 and color = green to update the state of a resource."
Slides 15 and 16 in one picture. The query string is not part of the resource's identity; it carries the arguments for the operation.
الشريحتان 15 و16 في صورة واحدة. نص الاستعلام ليس جزءاً من هوية الـ resource، بل يحمل وسائط العملية.
ItemالعنصرDescription (slide 15)الوصف (الشريحة 15)
www.myhome.comserverالخادم (server)
/lampsHTTP route: where to deliver the HTTP requestHTTP route: المكان الذي يُسلَّم إليه طلب HTTP
/123resource: the method in the HTTP request will operate on this resourceresource: الـ method في طلب HTTP سيعمل على هذا الـ resource
?brightness=6&color=greeninput to the operation on the resourceمدخلات العملية على الـ resource

الجدول بالعربية: www.myhome.com هو الـ server. و/lamps هو الـ HTTP route، أي إلى أين يُسلَّم الطلب. و/123 هو الـ resource الذي سيعمل عليه الـ method. و?brightness=6&color=green هو المدخلات للعملية على الـ resource.

The query string syntax: it starts at ?, holds key=value pairs, and separates pairs with &. Here there are two parameters: brightness with value 6 and color with value green.

صيغة الـ query string: تبدأ عند ?، وتحتوي أزواجاً بصيغة key=value، ويُفصل بين الأزواج بـ &. وهنا معاملان: brightness بالقيمة 6، وcolor بالقيمة green.

Slide 16's model: think of the request as running a program on the server. The resource (/123) says which lamp the program acts on, the query parameters are its arguments, and the output is the lamp's new state. Its boxed takeaway: the inputs to the program are given explicitly in the URL. The URL itself does not name the method; since the goal is to change an existing lamp's state, the matching method is PUT.

نموذج الشريحة 16: اعتبر الطلب تشغيلاً لبرنامج على الخادم. الـ resource (/123) يحدد المصباح الذي يعمل عليه البرنامج، والـ query parameters هي مدخلاته، والناتج هو الحالة الجديدة للمصباح. والخلاصة المؤطّرة: مدخلات البرنامج معطاة صراحة داخل الـ URL. والـ URL نفسه لا يذكر الـ method، وبما أن الهدف تغيير حالة مصباح موجود فالـ method المناسب هو PUT.

Worked example: dissect a new URLمثال محلول: شرّح URL جديداً

PUT http://www.myhome.com/lamps/7?state=off

server          www.myhome.com
route           /lamps
resource        /7               lamp number 7, one item
query string    ?state=off       one parameter: key state, value off
method          PUT              Update
effect          lamp 7 is switched off; send it again and it stays off (idempotent)

Change it to PUT /lamps?state=off and the resource part disappears: the target is now the whole collection, so every lamp switches off.

لو غيّرته إلى PUT /lamps?state=off يختفي جزء الـ resource، فيصبح الهدف الـ collection كلها، وتنطفئ كل المصابيح.

Exam trapsفخاخ الامتحان

1. POST to /visits/:id. It is the error row on slide 14. With an ID, use PUT to update; to create, POST to /visits.

1. POST على /visits/:id. هو صف الخطأ في الشريحة 14. مع وجود معرّف استخدم PUT للتحديث، وللإنشاء استخدم POST على /visits.

2. Collection vs item. "DELETE /lamps" disables all lamps, not one. Read the path before the method.

2. collection أم item؟ DELETE /lamps يعطّل كل المصابيح وليس مصباحاً واحداً. اقرأ المسار قبل الـ method.

3. Query parameters are inputs, not the resource. In /lamps/123?brightness=6 the resource is /123. brightness=6 is an argument to the operation.

3. الـ query parameters مدخلات وليست الـ resource. في /lamps/123?brightness=6 الـ resource هو /123، وbrightness=6 معامل للعملية.

4. /visits/new is a GET that shows a form. It does not create anything. The create happens when the form is submitted with POST /visits.

4. /visits/new هو GET يعرض نموذجاً فقط. لا يُنشئ شيئاً، والإنشاء يحدث عند إرسال النموذج بـ POST /visits.

Matching drill: method + path to purpose

تدريب توصيل: method مع المسار مقابل الغرض

GET /visits/new

C. A GET never creates. /visits/new is a fixed route for the form; the create is POST /visits. D is a real routing pitfall: /visits/new must be matched before /visits/:id, or "new" would be read as an ID.

C. طلب GET لا يُنشئ شيئاً أبداً. و/visits/new مسار ثابت للنموذج، أما الإنشاء فهو POST /visits. والخيار D مشكلة حقيقية في التوجيه: يجب مطابقة /visits/new قبل /visits/:id، وإلا قُرئت "new" على أنها معرّف.

POST /visits

A. POST on the collection creates a new item and the server assigns its ID.

A. الـ POST على المجموعة يُنشئ عنصراً جديداً، والخادم هو من يعيّن معرّفه.

POST /visits/:id

D. The red row on slide 14, "Do not do this!". B describes what you should have done, but with PUT, not POST.

D. هو الصف الأحمر في الشريحة 14، "Do not do this!" أي لا تفعل هذا. والخيار B يصف ما كان يجب أن تفعله، لكن بـ PUT لا بـ POST.

DELETE /lamps

B. No ID in the path means the collection, so every lamp is disabled. A is DELETE /lamps/123.

B. عدم وجود معرّف في المسار يعني المجموعة، فتُعطَّل كل المصابيح. والخيار A هو DELETE /lamps/123.

PUT /lamps/123

C. PUT updates, and the ID narrows it to one lamp. B is PUT /lamps, D is DELETE /lamps/123, A is GET /lamps/123.

C. الـ PUT يحدّث، والمعرّف يضيّقه إلى مصباح واحد. والخيار B هو PUT /lamps، وD هو DELETE /lamps/123، وA هو GET /lamps/123.

Check yourself

اختبر نفسك

In http://www.myhome.com/lamps/123?brightness=6&color=green, what is ?brightness=6&color=green according to slide 15?

في http://www.myhome.com/lamps/123?brightness=6&color=green، ما هو ?brightness=6&color=green بحسب الشريحة 15؟

B. The query string carries the inputs (the new brightness and color). The resource is /123, the route is /lamps, the server is www.myhome.com.

B. نص الاستعلام يحمل المدخلات (السطوع واللون الجديدين). والـ resource هو /123، والـ route هو /lamps، والخادم هو www.myhome.com.

In the same URL, what does slide 15 say /lamps is?

في نفس الـ URL، ماذا تقول الشريحة 15 عن /lamps؟

A. Route = where to deliver; resource (/123) = what the method operates on. Mixing these two is the point of the question.

A. الـ Route = مكان التسليم، والـ resource (/123) = ما يعمل عليه الـ method. والخلط بين هذين هو هدف السؤال.

What decides whether an HTTP method affects all lamps or only one (slide 13)?

ما الذي يحدد هل يؤثر الـ HTTP method على كل المصابيح أم على مصباح واحد (الشريحة 13)؟

D. The slide's footer says exactly this. The collection path targets all lamps, the item path targets one. The query string supplies values, not the scope.

D. هذا بالضبط ما يقوله تذييل الشريحة. مسار المجموعة يستهدف كل المصابيح، ومسار العنصر يستهدف مصباحاً واحداً. ونص الاستعلام يقدّم القيم، لا النطاق.

How many query parameters are in ?brightness=6&color=green, and what separates them?

كم query parameter في ?brightness=6&color=green، وما الذي يفصل بينها؟

C. Two key=value pairs, brightness=6 and color=green, joined by &. The ? marks where the query string starts; = joins a key to its value.

C. زوجان من key=value، هما brightness=6 وcolor=green، يربط بينهما &. وعلامة ? تحدد أين يبدأ نص الاستعلام، و= تربط المفتاح بقيمته.