APIs, endpoints and routesواجهات 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) دون أن يلاحظ العميل.