Lecture 03 · Application Programming Interfaces
المحاضرة 03 · واجهات برمجة التطبيقات
What an API is: interface, protocol, endpoint, resource
ما هو الـ API: interface وprotocol وendpoint وresource
P1 MUSTFour words that the exam loves to swap: the API is what you call, the protocol is how you call it, the endpoint is where you call it, and the resource is what you are really after.
أربع كلمات يحب الامتحان أن يبدّل بينها: API هو ما تستدعيه، وprotocol هو كيف تستدعيه، وendpoint هو المكان الذي تستدعيه فيه، وresource هو الشيء الذي تريده فعلاً.
The API layer sits in the middle
طبقة الـ API تقع في المنتصف
Slide 2 defines an API in one line: it allows different software components to communicate with each other. The picture puts it as a middle layer between the front-end and the back-end of an application, with two jobs that run in opposite directions:
تعرّف الشريحة 2 الـ API في سطر واحد: هو ما يسمح لمكوّنات برمجية مختلفة بأن تتواصل مع بعضها. والرسم يضعه كطبقة وسطى بين front-end وback-end للتطبيق، وله مهمتان في اتجاهين متعاكسين:
- Downward then up (read path): fetch data from the back-end and display it on the front-end.
مسار القراءة: يجلب البيانات من back-end ويعرضها على front-end.
- Up then down (write path): take data from the front-end and insert it into the back-end.
مسار الكتابة: يأخذ البيانات من front-end ويُدخلها في back-end.
The slide's boxed takeaway: "API acts as interface between components." The front-end never talks to the database directly. It talks to the API, and the API owns the rules for reading and writing.
والخلاصة المؤطّرة في الشريحة: "API acts as interface between components." أي أن API هو الواجهة بين المكوّنات. الواجهة الأمامية لا تكلّم قاعدة البيانات مباشرة أبداً، بل تكلّم API، وAPI هو من يملك قواعد القراءة والكتابة.
Interface, protocol, connection: three different things
Interface وprotocol وconnection: ثلاثة أشياء مختلفة
Slide 3 draws two components, each with a red box labelled Web API. A green arrow between the two boxes is labelled Interface. A blue line underneath, joining them physically, is labelled HTTP / Protocol / Connection. The headline sentence: a Web API is the interface; HTTP is the protocol used to implement the communication.
ترسم الشريحة 3 مكوّنين، لكل منهما مربع أحمر مكتوب عليه Web API. السهم الأخضر بين المربعين اسمه Interface، والخط الأزرق تحته الذي يربطهما فعلياً مكتوب عليه HTTP / Protocol / Connection. والجملة الرئيسية: Web API هو الواجهة، وHTTP هو البروتوكول الذي يُنفَّذ به التواصل.
| Termالمصطلح | Slide 3 definitionتعريف الشريحة 3 | Question it answersالسؤال الذي يجيب عنه | In the HTTP worldفي عالم HTTP |
|---|---|---|---|
| API (interface)API (الواجهة) | what you can callما يمكنك استدعاؤه | Which operations exist?ما العمليات الموجودة؟ | the set of method + URL routes the server offersمجموعة مسارات method + URL التي يقدّمها الخادم |
| ProtocolProtocol (البروتوكول) | how you call itكيف تستدعيه | What do the messages look like, in what order?كيف تبدو الرسائل، وبأي ترتيب؟ | HTTP: request line, headers, body, status codesHTTP: سطر الطلب، والـ headers، والـ body، وstatus codes |
| ConnectionConnection (الاتصال) | how the data physically travelsكيف تنتقل البيانات فعلياً | What carries the bytes?ما الذي يحمل البايتات؟ | a TCP connection over IP, over the linkاتصال TCP فوق IP، فوق الوصلة |
احفظ الجدول كثلاث جمل: API = ما يمكنك استدعاؤه (أي العمليات الموجودة)، وProtocol = كيف تستدعيه (شكل الرسائل وترتيبها، وفي حالتنا HTTP بسطر الطلب والـ headers والـ body وstatus codes)، وConnection = كيف تنتقل البيانات فعلياً (اتصال TCP فوق IP).
Lecture 01 said a relationship between two components = protocol + interface. Slide 3 is the same sentence with real names plugged in: the interface is the Web API, the protocol is HTTP. The connection is the layer underneath both, which is why Lecture 01 kept it out of the relationship on purpose.
قالت المحاضرة 01 إن العلاقة بين مكوّنين = protocol + interface. والشريحة 3 هي الجملة نفسها بعد وضع الأسماء الحقيقية: الـ interface هو Web API، والـ protocol هو HTTP. أما connection فهو الطبقة التي تحت الاثنين، ولهذا أبقته المحاضرة 01 خارج تعريف العلاقة عن قصد.
The API on the server is called an endpoint
الـ API على الخادم يُسمّى endpoint
Slide 4: an HTTP client sends multiple requests to an HTTP server. The server exposes several numbered boxes (1, 2, 3), and each one is an endpoint. Three facts from the slide:
الشريحة 4: الـ HTTP client يرسل عدة طلبات إلى HTTP server. والخادم يعرض عدة مربعات مرقّمة (1, 2, 3)، وكل واحد منها هو endpoint. وفي الشريحة ثلاث حقائق:
- The client sends multiple requests to the server.
- The server has multiple endpoints, each handling different API routes.
- The endpoint is where the API processes the request and returns data.
العميل يرسل طلبات متعددة إلى الخادم. والخادم فيه أكثر من endpoint، كل منها يتعامل مع API routes مختلفة. والـ endpoint هو المكان الذي يعالج فيه الـ API الطلب ويُرجع البيانات.
Slide 7 closes the loop from the client's side: every interaction is one request out and one response back, and for the client, the HTTP server is a set of APIs. The client cannot see code, files or databases. All it can see is the list of endpoints it is allowed to call.
وتُغلق الشريحة 7 الدائرة من جهة العميل: كل تفاعل هو request يخرج وresponse يعود، وبالنسبة للعميل، الـ HTTP server ما هو إلا مجموعة من APIs. العميل لا يرى الكود ولا الملفات ولا قواعد البيانات، كل ما يراه هو قائمة الـ endpoints المسموح له باستدعائها.
What does an endpoint represent?
ماذا يمثّل الـ endpoint؟
Slide 5 is the definition to memorise word for word:
الشريحة 5 فيها التعريف الذي يجب حفظه حرفياً:
An abstraction of a resource
تجريد لـ resource
The client interacts with an endpoint that manages a resource. It never touches the resource directly.
العميل يتعامل مع endpoint يدير الـ resource، ولا يلمس الـ resource مباشرة أبداً.
Four operations: CRUD
أربع عمليات: CRUD
Create, Read, Update, Delete. These are the four basic operations an endpoint supports on its resource.
Create, Read, Update, Delete: هذه هي العمليات الأساسية الأربع التي يدعمها الـ endpoint على الـ resource الخاص به.
Plus the logic
ومعها المنطق
The endpoint also provides the logic needed to execute those four operations: validation, lookup, writing to storage.
والـ endpoint يوفّر أيضاً المنطق اللازم لتنفيذ هذه العمليات الأربع: التحقق من المدخلات، والبحث، والكتابة في التخزين.
The slide's summary box: endpoints act as access points for retrieving or modifying resources. In the diagram the endpoint and the resource both live inside the dashed HTTP Server box, and only the endpoint has an arrow to the client.
ومربع الخلاصة في الشريحة: الـ endpoints هي نقاط وصول لاسترجاع الـ resources أو تعديلها. وفي الرسم يقع الـ endpoint والـ resource كلاهما داخل المربع المتقطّع الخاص بالـ HTTP Server، ولا يوجد سهم إلى العميل إلا من الـ endpoint.
Endpoints and routes
الـ Endpoints والـ routes
Slide 6 adds the last piece. A URL leads to an endpoint, and the endpoint defines routes to manage different actions. A resource can be exposed through several API operations, distinguished by the HTTP method and the URL path. The magenta label on the slide spells it out:
تضيف الشريحة 6 القطعة الأخيرة. الـ URL يقود إلى endpoint، والـ endpoint يعرّف routes لإدارة الأفعال المختلفة. ويمكن عرض resource واحد عبر عدة عمليات API، يُميَّز بينها بـ HTTP method وURL path. والعنوان البنفسجي في الشريحة يقولها صراحة:
route = HTTP method + URL
So GET /lamps/123 and DELETE /lamps/123 are two different routes on the same URL. Same path, different method, different operation. The slide's three closing bullets: the server hosts the endpoint, the client talks to the endpoint through specific routes, and the routes correspond to CRUD operations on that endpoint.
إذن GET /lamps/123 وDELETE /lamps/123 هما route مختلفان على نفس الـ URL: نفس المسار، method مختلف، عملية مختلفة. والنقاط الثلاث في آخر الشريحة: الـ server يستضيف الـ endpoint، والـ client يتواصل مع الـ endpoint عبر routes محددة، والـ routes تقابل عمليات CRUD على ذلك الـ endpoint.
A client sends PUT http://myhome.com/lamps/123 to switch a lamp on. Name each piece.
عميل يرسل PUT http://myhome.com/lamps/123 لتشغيل مصباح. سمِّ كل جزء.
Interface (API) the set of routes myhome.com offers, including PUT /lamps/:id Protocol HTTP, the request is "PUT /lamps/123 HTTP/1.1" plus headers and body Connection the TCP connection carrying those bytes to myhome.com Endpoint /lamps/123 on the server, the access point that manages lamp 123 Resource lamp 123 itself (its on/off state, brightness, color) Route PUT + /lamps/123 CRUD operation Update
If you can fill all seven lines without looking, you own slides 2 to 7.
إذا استطعت ملء الأسطر السبعة دون أن تنظر، فقد أتقنت الشرائح من 2 إلى 7.
1. API vs protocol vs connection. A matching question will list "what you can call", "how you call it", "how the data physically travels". The answers are API, protocol, connection, in that order. HTTP is the protocol, not the API. A Web API uses HTTP; it is not HTTP.
1. API مقابل protocol مقابل connection. سؤال التوصيل سيعطيك "ما يمكنك استدعاؤه" و"كيف تستدعيه" و"كيف تنتقل البيانات فعلياً"، والإجابات بالترتيب: API ثم protocol ثم connection. وHTTP هو البروتوكول وليس الـ API. الـ Web API يستخدم HTTP لكنه ليس HTTP.
2. The endpoint is not the resource. It is an abstraction of, and access point to, the resource. Deleting through an endpoint removes the resource; the endpoint (the route that handles it) still exists and will answer, for example with 404 Not Found.
2. الـ endpoint ليس هو الـ resource. هو تجريد للـ resource ونقطة وصول إليه. الحذف عبر الـ endpoint يزيل الـ resource، لكن الـ endpoint نفسه (الـ route الذي يعالجه) يبقى موجوداً ويردّ، مثلاً بـ 404 Not Found.
3. A route is method plus path, not path alone. "How many routes does /visits/:id have?" Count the methods: GET, PUT, DELETE make three routes on one path.
3. الـ route هو method مع المسار، وليس المسار وحده. لو سُئلت "كم route على /visits/:id؟" فعُدّ الـ methods: GET وPUT وDELETE تعطي ثلاثة routes على مسار واحد.
Check yourself
اختبر نفسك
Match slide 3's summary: "how the data physically travels" describes which term?
بحسب خلاصة الشريحة 3: عبارة "كيف تنتقل البيانات فعلياً" تصف أي مصطلح؟
C. API = what you can call, protocol = how you call it, connection = how the data physically travels. B is the most common swap: HTTP defines the message format and rules, but the bytes ride on a TCP connection underneath.
C. API = ما يمكنك استدعاؤه، وprotocol = كيف تستدعيه، وconnection = كيف تنتقل البيانات فعلياً. والخيار B هو الخلط الأكثر شيوعاً: HTTP يحدد شكل الرسائل وقواعدها، لكن البايتات تنتقل فوق اتصال TCP تحته.
In slide 3, which statement is correct?
في الشريحة 3، أي عبارة صحيحة؟
B, quoted from the slide. It is also Lecture 01's "relationship = protocol + interface" with names filled in. D confuses protocol with connection.
B، مقتبسة من الشريحة. وهي أيضاً جملة المحاضرة 01 "العلاقة = protocol + interface" بعد ملء الأسماء. والخيار D يخلط بين البروتوكول والاتصال.
According to slide 5, what is an endpoint?
بحسب الشريحة 5، ما هو الـ endpoint؟
A. The endpoint manages the resource and is the client's access point to it. B is the classic trap: the endpoint is the door, not the room. C mixes in transport-layer addressing. D is the wrong side of the wire; the API on the server is the endpoint.
A. الـ endpoint يدير الـ resource وهو نقطة وصول العميل إليه. والخيار B هو الفخ الكلاسيكي: الـ endpoint هو الباب لا الغرفة. والخيار C يُدخل عنونة طبقة النقل. والخيار D في الطرف الخطأ من الخط، فالـ API على الخادم هو الـ endpoint.
Two requests hit the same URL, /lamps/123, one with GET and one with DELETE. How does slide 6 describe this?
طلبان على نفس الـ URL وهو /lamps/123، أحدهما GET والآخر DELETE. كيف تصف الشريحة 6 هذا؟
D. A resource can be exposed through multiple API operations distinguished by HTTP method and URL path. Same path with a different method is a different route and a different CRUD operation (Read vs Delete).
D. يمكن عرض resource واحد عبر عدة عمليات API يُميَّز بينها بالـ HTTP method والـ URL path. نفس المسار مع method مختلف هو route مختلف وعملية CRUD مختلفة (Read مقابل Delete).
From the client's point of view (slide 7), the HTTP server is:
من وجهة نظر العميل (الشريحة 7)، الـ HTTP server هو:
B. The client sends a request, gets a response, and that is all it sees. The server shows up as several endpoints (1, 2, 3 on the slide), each one an API. C contradicts slide 4's multiple endpoints.
B. العميل يرسل طلباً ويستقبل استجابة، وهذا كل ما يراه. والخادم يظهر له كعدة endpoints (1, 2, 3 في الشريحة)، كل واحد منها API. والخيار C يناقض تعدد الـ endpoints في الشريحة 4.