Designing endpoints: collections, items and query stringsتصميم نقاط النهاية: المجموعات والعناصر وسلاسل الاستعلام

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.كل ما قبل ? يقول أين، وكل ما بعده يقول بماذا.