Application Programming Interfaces (APIs)واجهات برمجة التطبيقات (APIs)

AOverviewنظرة عامة

Lecture 01 switched a lamp on from a browser. This lecture opens the arrow between that browser and the server and names every piece of it: the API, the protocol, the connection, the endpoint, the resource and the route. It then shows the exact text that travels as an HTTP request and response, how to shape URLs so a method touches one lamp or all of them, and the six REST constraints that turn "some HTTP calls" into an API that scales.

في المحاضرة 01 شغّلنا مصباحًا من المتصفح. هذه المحاضرة تفتح السهم الذي يربط ذلك المتصفح بالخادم وتسمّي كل جزء فيه: الـAPI، والبروتوكول (protocol)، والاتصال (connection)، ونقطة النهاية (endpoint)، والمورد (resource)، والمسار (route). ثم تعرض النص الحرفي الذي ينتقل على شكل طلب HTTP واستجابته، وكيف نصمّم عناوين URL بحيث تؤثر الطريقة (method) على مصباح واحد أو على كل المصابيح، وقيود REST الستة التي تحوّل "مجموعة استدعاءات HTTP" إلى API قابل للتوسع.

As a PhD student in edge and cloud computing you need it for three things. The midterm asks you to tell close terms apart (endpoint versus route, PUT versus POST, stateless versus stateful) and to fill in an API design table without hesitating. The research project needs a clean interface between its device, edge and cloud components, and that interface is an API. And every later topic in the course, from load balancers to edge caches, assumes the stateless, cacheable, layered style taught here.

بصفتك طالب دكتوراه في الحوسبة الطرفية والسحابية تحتاج هذا لثلاثة أمور. الاختبار النصفي يطلب منك التمييز بين مصطلحات متقاربة (endpoint مقابل route، وPUT مقابل POST، وstateless مقابل stateful) وملء جدول تصميم API دون تردد. ومشروعك البحثي يحتاج واجهة نظيفة بين مكوّنات الجهاز والطرف (edge) والسحابة، وهذه الواجهة هي API. وكل موضوع لاحق في المقرر، من موازنات الحمل (load balancers) إلى ذاكرات التخزين المؤقت الطرفية (edge caches)، يفترض الأسلوب عديم الحالة (stateless) والقابل للتخزين المؤقت (cacheable) والطبقي (layered) الذي نشرحه هنا.

The path has five stops. You place the API as the middle layer and split it from the protocol and the connection. You read every line of an HTTP message and map CRUD onto methods. You design collection and item URLs and parse a query string. You learn REST as a style with six constraints, one of them optional. Finally you apply the five design elements to a smart-home lamp API and a calculator API.

للمسار خمس محطات. تضع الـAPI كطبقة وسطى وتفصله عن البروتوكول والاتصال. تقرأ كل سطر في رسالة HTTP وتربط عمليات CRUD بالطرق (methods). تصمّم عناوين URL للمجموعة (collection) وللعنصر (item) وتحلّل سلسلة الاستعلام (query string). تتعلم REST كأسلوب معماري له ستة قيود، أحدها اختياري. وأخيرًا تطبّق عناصر التصميم الخمسة على API لمصباح منزل ذكي وعلى API لآلة حاسبة.

Success looks likeعلامات النجاح

• Separate API (what you can call), protocol (how you call it) and connection (how the data travels), and define endpoint, resource and route with a lamp example.تفصل بين الـAPI (ما يمكنك استدعاؤه)، والبروتوكول (كيف تستدعيه)، والاتصال (كيف تنتقل البيانات)، وتعرّف endpoint وresource وroute بمثال المصباح.
• Map Create, Read, Update and Delete to POST, GET, PUT and DELETE, and say which methods are safe and idempotent.تربط Create وRead وUpdate وDelete بـPOST وGET وPUT وDELETE، وتذكر أي الطرق آمنة (safe) وأيها متساوية الأثر (idempotent).
• Label every part of a raw HTTP request and response, read a status code by its class, and compute a Content-Length.تسمّي كل جزء في طلب HTTP خام وفي استجابته، وتقرأ رمز الحالة من فئته، وتحسب قيمة Content-Length.
• Design collection and item URLs, spot the POST /visits/:id mistake, and split a URL into server, route, resource and query inputs.تصمّم عناوين URL للمجموعة وللعنصر، وتكتشف خطأ POST /visits/:id، وتقسّم الـURL إلى الخادم (server) والمسار (route) والمورد (resource) ومدخلات الاستعلام (query inputs).
• List the six REST constraints in order, mark code on demand as the optional one, and decide from max-age whether a request is served from cache.تسرد قيود REST الستة بالترتيب، وتحدد code on demand على أنه القيد الاختياري، وتقرر من قيمة max-age هل يُخدَم الطلب من ذاكرة التخزين المؤقت (cache).
• Design a REST API with the five design elements and choose the right status code (200, 400, 406, 500, 503) for each outcome.تصمّم REST API بعناصر التصميم الخمسة وتختار رمز الحالة الصحيح (200، 400، 406، 500، 503) لكل نتيجة.

How to study this lectureكيف تذاكر هذه المحاضرة

1. Choose your route. Read the full guide in one sitting for the big picture, or work through one part at a time when you want depth.اختر طريقتك. اقرأ الدليل الكامل في جلسة واحدة لترى الصورة الكبيرة، أو ادرس جزءًا واحدًا في كل مرة حين تريد التعمق.
2. Answer every recall prompt in your head, or on paper, before you reveal it. The effort of retrieving is what makes the idea stick.أجب عن كل سؤال استرجاع في ذهنك، أو على ورقة، قبل أن تكشف الإجابة. جهد الاسترجاع نفسه هو ما يثبّت الفكرة.
3. Take each quiz and read the explanation even when you are right.حلّ كل اختبار قصير واقرأ الشرح حتى عندما تكون إجابتك صحيحة.
4. Redraw the lamp API table and the calculator table from memory on a blank page. These two tables are the most likely design questions.أعد رسم جدول API المصباح وجدول الآلة الحاسبة من الذاكرة على صفحة فارغة. هذان الجدولان هما أكثر أسئلة التصميم احتمالًا.
5. Mark a concept as understood only when you could explain it to a classmate without looking. Unmarked concepts show you where to return.لا تضع علامة "فهمته" على مفهوم إلا إذا كنت تستطيع شرحه لزميل دون أن تنظر. المفاهيم غير المعلَّمة تدلّك على ما يجب أن تعود إليه.
6. Keep the glossary open for terms, and use the reference sheet for tables, status codes and slide errata when you review. Come back after a few days and retry the prompts cold.أبقِ المسرد (glossary) مفتوحًا للمصطلحات، واستخدم الورقة المرجعية للجداول ورموز الحالة وأخطاء الشرائح عند المراجعة. عد بعد بضعة أيام وأعد محاولة الأسئلة دون تحضير.

BThe 5 partsالأجزاء الـ5

1. 01APIs, endpoints and routesواجهات APIs ونقاط النهاية والمساراتThe API as the layer between components, the split between interface, protocol and connection, and how a server exposes resources through endpoints and routes.واجهة API بوصفها الطبقة الوسيطة بين المكونات، والفصل بين الواجهة (interface) والبروتوكول (protocol) والاتصال (connection)، وكيف يعرض الخادم موارده عبر نقاط النهاية (endpoints) والمسارات (routes).4 concepts4 مفاهيمSlides 1-7الشرائح 1-724 min24 دقيقة
   1. 1.1The API as the contract between componentsالـ API بوصفه العقد بين المكوّنات
   2. 1.2What you call, how you call it, how it travelsما تستدعيه، وكيف تستدعيه، وكيف ينتقل
   3. 1.3An endpoint is an abstraction of a resourceنقطة النهاية (endpoint) تجريد لمورد
   4. 1.4Routes: HTTP method plus URL, and the server as a set of APIsالمسارات: طريقة HTTP زائد عنوان URL، والخادم بوصفه مجموعة من الـ APIs
2. 02HTTP methods and message anatomyطرق HTTP وتشريح الرسائلHow the four CRUD operations map onto GET, POST, PUT and DELETE, and how to read every field of an HTTP request and response using the index.html example.كيف تُربط عمليات CRUD الأربع بالطرق GET وPOST وPUT وDELETE، وكيف تقرأ كل حقل في طلب HTTP واستجابته باستخدام مثال index.html.3 concepts3 مفاهيمSlides 8-12الشرائح 8-1218 min18 دقيقة
   1. 2.1Four HTTP methods for four CRUD operationsأربع طرق HTTP لأربع عمليات CRUD
   2. 2.2Anatomy of an HTTP requestتشريح طلب HTTP
   3. 2.3Anatomy of an HTTP responseتشريح استجابة HTTP
3. 03Designing endpoints: collections, items and query stringsتصميم نقاط النهاية: المجموعات والعناصر وسلاسل الاستعلامHow the shape of a URL decides what a method acts on: collection versus item endpoints in the smart-home lamp API, a full route table, the POST-on-an-ID mistake, and URL query parameters as inputs.كيف يحدد شكل عنوان URL ما تعمل عليه الطريقة: نقطة نهاية المجموعة (collection) مقابل نقطة نهاية العنصر (item) في واجهة API لمصباح المنزل الذكي، وجدول مسارات كامل، وخطأ استخدام POST على معرّف (ID)، ومعاملات الاستعلام (query parameters) في URL بوصفها مدخلات.3 concepts3 مفاهيمSlides 13-16الشرائح 13-1618 min18 دقيقة
   1. 3.1Collection versus item: the URL decides what a method touchesالمجموعة مقابل العنصر: الـ URL يحدد ما تؤثر فيه الـ method
   2. 3.2The resourceful route table and the POST-on-an-ID mistakeجدول المسارات الموردية (resourceful routes) وخطأ استخدام POST على ID
   3. 3.3Reading a URL: server, route, resource and query inputsقراءة الـ URL: الخادم والمسار والمورد ومدخلات الاستعلام
4. 04REST: the style and its six constraintsREST: الأسلوب وقيوده الستةWhat REST is and is not, the six architectural constraints (five mandatory, code on demand optional), the four sub-constraints of the uniform interface, and the five design elements every REST API must specify.ما هو REST وما ليس هو، وقيوده المعمارية الستة (خمسة إلزامية، و code on demand اختياري)، والقيود الفرعية الأربعة للواجهة الموحدة (uniform interface)، وعناصر التصميم الخمسة التي يجب أن تحددها كل واجهة REST API.4 concepts4 مفاهيمSlides 17-21الشرائح 17-2124 min24 دقيقة
   1. 4.1REST is an architectural style, not a protocolREST أسلوب معماري وليس بروتوكولًا
   2. 4.2Client-server, statelessness and cacheabilityفصل العميل عن الخادم، وانعدام الحالة، وقابلية التخزين المؤقت
   3. 4.3Uniform interface, layered system and code on demandالواجهة الموحدة، والنظام الطبقي، والشيفرة عند الطلب
   4. 4.4From constraints to design: resources, JSON, headers and the five elementsمن القيود إلى التصميم: الموارد، وJSON، والترويسات، والعناصر الخمسة
5. 05Designing REST APIs: the lamp system and the calculatorتصميم واجهات REST API: نظام المصباح والآلة الحاسبةThe five design elements applied end to end: the full smart-home lamp API with headers and JSON bodies, then the calculator addition API with status codes, and how to design the other operations yourself.عناصر التصميم الخمسة مطبقةً من البداية إلى النهاية: واجهة API الكاملة لمصباح المنزل الذكي مع الترويسات (headers) وأجسام JSON، ثم واجهة API للجمع في الآلة الحاسبة مع رموز الحالة (status codes)، وكيف تصمم بقية العمليات بنفسك.5 concepts5 مفاهيمSlides 22-27الشرائح 22-2730 min30 دقيقة
   1. 5.1The lamp system: from a button click to a signalنظام المصباح: من ضغطة زر إلى إشارة
   2. 5.2Completing the lamp API tableإكمال جدول API المصباح
   3. 5.3The five design elements as a checklistعناصر التصميم الخمسة كقائمة تحقق
   4. 5.4Designing the calculator's addition APIتصميم API الجمع في الآلة الحاسبة
   5. 5.5Designing subtraction, multiplication and division yourselfصمّم الطرح والضرب والقسمة بنفسك

CGlossary and referenceالمصطلحات والمرجع

• GlossaryالمصطلحاتEvery term from the lecture, defined once, with links back to the slides that use it.كل مصطلح في المحاضرة معرّف مرة واحدة، مع روابط تعيدك إلى الشرائح التي تستخدمه.
• Reference sheetالورقة المرجعيةThe lecture on one printable page, for revision before a quiz or exam.المحاضرة كاملة في صفحة واحدة قابلة للطباعة، للمراجعة قبل الاختبار القصير أو الامتحان.