HTTP methods and message anatomyطرق HTTP وتشريح الرسائل

Think of a smart lamp exposed through an API. You might add a new lamp to the system, ask for its current state, set it to a new state, or retire it. Those four actions are all an application ever does to stored data, and HTTP has one verb for each.

تخيّل مصباحًا ذكيًا متاحًا عبر API. قد تضيف مصباحًا جديدًا إلى النظام، أو تسأل عن حالته الحالية، أو تضبطه على حالة جديدة، أو تُخرجه من الخدمة. هذه الأفعال الأربعة هي كل ما يفعله أي تطبيق بالبيانات المخزنة، ولـ HTTP فعل واحد لكل منها.

The table to memorizeالجدول الذي يجب حفظه

The four actions are the CRUD operations: Create, Read, Update, Delete. Each request names its operation with an HTTP method, the verb at the very start of the message. The lecture maps them like this: POST creates a new Resource, GET returns one, PUT updates or replaces one, and DELETE removes one.

الأفعال الأربعة هي عمليات CRUD: الإنشاء (Create)، والقراءة (Read)، والتحديث (Update)، والحذف (Delete). كل طلب يسمّي عمليته بـ HTTP method، وهو الفعل الموجود في بداية الرسالة تمامًا. وتربطها المحاضرة هكذا: POST ينشئ resource جديدًا، وGET يُرجع موردًا، وPUT يحدّث موردًا أو يستبدله، وDELETE يحذفه.

Slide 8 lists GET first. Slide 9 lists the same four in CRUD order, so POST comes first. The mapping is identical; only the row order changed. If an exam table is shuffled, anchor on the pair people swap: you POST a new item (Create) and GET an existing one (Read). DELETE is Delete, and PUT is the one left, Update.

الشريحة 8 تضع GET أولًا. والشريحة 9 تسرد الطرق الأربع نفسها بترتيب CRUD، فتأتي POST أولًا. الربط متطابق؛ لم يتغير إلا ترتيب الصفوف. إذا جاء جدول في الامتحان مخلوط الترتيب، فاعتمد على الزوج الذي يخلط الناس بينه: ترسل عنصرًا جديدًا بـ POST (إنشاء)، وتجلب عنصرًا موجودًا بـ GET (قراءة). DELETE هي الحذف، وPUT هي المتبقية، أي التحديث.

PUT replaces, PATCH editsPUT يستبدل، وPATCH يعدّل

The slides write PUT as "Update / Replace", and the word replace is the precise one. A PUT sends the full new state of the resource at a URL the client already knows, and the server stores exactly that. If you PUT a lamp with only a brightness field, a strict server would forget the lamp's colour. For changing one field there is PATCH, defined in RFC 5789, which sends only a set of changes. PATCH does not appear in the tables on slides 8 and 9, but it appears on slide 19, so meet it now.

تكتب الشرائح PUT على أنها "Update / Replace"، وكلمة الاستبدال (replace) هي الأدق. طلب PUT يرسل الحالة الجديدة الكاملة للمورد إلى URL يعرفه العميل مسبقًا، والخادم يخزّن ذلك بالضبط. إذا أرسلت PUT لمصباح بحقل السطوع (brightness) فقط، فإن الخادم الصارم سينسى لون المصباح. لتغيير حقل واحد توجد PATCH، المعرّفة في RFC 5789، وهي ترسل مجموعة من التغييرات فقط. لا تظهر PATCH في جدولي الشريحتين 8 و9، لكنها تظهر في الشريحة 19، لذا تعرّف عليها الآن.

Beyond the slides: safe and idempotentخارج الشرائح: الآمن (safe) ومتساوي الأثر (idempotent)

A method is safe when it does not ask the server to change anything. GET is safe: reading a lamp's state never turns it on. That is why browsers, caches and crawlers feel free to send GET requests on their own.

تكون الطريقة آمنة (safe) عندما لا تطلب من الخادم تغيير أي شيء. GET آمنة: قراءة حالة المصباح لا تشغّله أبدًا. ولهذا تشعر المتصفحات والـ caches وبرامج الزحف (crawlers) بحرية إرسال طلبات GET من تلقاء نفسها.

A method is Idempotent method when sending the same request twice leaves the server in the same state as sending it once. Picture a flaky mobile connection: the app sends a request, the reply is lost, and the app retries. Whether the retry is harmless depends on the method.

تكون الطريقة idempotent (متساوية الأثر) عندما يترك إرسال الطلب نفسه مرتين الخادمَ في الحالة نفسها التي يتركه فيها إرساله مرة واحدة. تخيّل اتصال جوال متقطعًا: يرسل التطبيق طلبًا، فيضيع الرد، فيعيد التطبيق المحاولة. كون إعادة المحاولة غير ضارة يعتمد على الطريقة.

• PUT /lamps/7 with state "on", sent twice: the lamp is "on" after the first and still "on" after the second. Idempotent.PUT /lamps/7 بالحالة "on"، مرسلًا مرتين: المصباح "on" بعد الأول وما زال "on" بعد الثاني. متساوية الأثر (idempotent).
• DELETE /lamps/7 sent twice: the first removes it, the second finds nothing. The response codes differ (often 200 then 404), but the end state, no lamp 7, is the same. Idempotent.DELETE /lamps/7 مرسلًا مرتين: الأول يحذفه، والثاني لا يجد شيئًا. رموز الاستجابة تختلف (غالبًا 200 ثم 404)، لكن الحالة النهائية، أي عدم وجود المصباح 7، هي نفسها. متساوية الأثر (idempotent).
• GET /lamps/7 sent twice: nothing changes at all. Safe, and therefore idempotent.GET /lamps/7 مرسلًا مرتين: لا يتغير أي شيء على الإطلاق. آمنة، وبالتالي متساوية الأثر.
• POST /lamps sent twice: two new lamps with two new IDs. Not idempotent.POST /lamps مرسلًا مرتين: مصباحان جديدان بمعرّفين (IDs) جديدين. ليست متساوية الأثر.

Type http://localhost/index.html into a browser. Before any page appears, the browser, acting as an HTTP client, writes a short text message and sends it to the HTTP server on your own machine.

اكتب http://localhost/index.html في المتصفح. قبل أن تظهر أي صفحة، يكتب المتصفح، بصفته HTTP client، رسالة نصية قصيرة ويرسلها إلى HTTP server على جهازك نفسه.

On the server side the lecture draws the picture of part 01: the Endpoint receives the request, reads the resource from the server's file system, and sends it back. Here the resource is a static file, index.html, so "reading" just means opening the file. Later in the lecture the same pattern will read a lamp's state from a database instead.

على جانب الخادم ترسم المحاضرة صورة الجزء 01: الـ endpoint يستقبل الطلب، ويقرأ المورد من نظام ملفات الخادم، ثم يعيده. هنا المورد ملف ثابت، index.html، لذا فإن "القراءة" تعني ببساطة فتح الملف. لاحقًا في المحاضرة سيقرأ النمط نفسه حالة المصباح من قاعدة بيانات بدلًا من ذلك.

The URL is split across the messageالـ URL يتوزع على أجزاء الرسالة

The URL does not travel as one piece. The host part, localhost, is used to find and connect to the server, and is repeated inside the message as the Host header. The path part, /index.html, goes into the first line. Here is the full request from slide 11:

الـ URL لا ينتقل قطعة واحدة. جزء المضيف (host)، أي localhost، يُستخدم لإيجاد الخادم والاتصال به، ويتكرر داخل الرسالة في ترويسة Host. وجزء المسار (path)، أي /index.html، يذهب إلى السطر الأول. وهذا هو الطلب الكامل من الشريحة 11:

The first line is the Request line. Its grammar in the HTTP/1.1 standard is exact: method, single space, request target, single space, version.

السطر الأول هو request line (سطر الطلب). وقواعده في معيار HTTP/1.1 دقيقة: الطريقة، ثم مسافة واحدة، ثم هدف الطلب، ثم مسافة واحدة، ثم الإصدار.

1. Request line: GET /index.html HTTP/1.1.سطر الطلب: GET /index.html HTTP/1.1.
2. Zero or more Header fields, one per line, each a name, a colon and a value.صفر أو أكثر من header fields (حقول الترويسة)، حقل في كل سطر، وكل حقل اسم ثم نقطتان رأسيتان (:) ثم قيمة.
3. An empty line (just CRLF, the two characters carriage return and line feed).سطر فارغ (مجرد CRLF، أي الحرفين: الرجوع إلى بداية السطر (carriage return) والانتقال إلى سطر جديد (line feed)).
4. An optional body. A GET normally has none; a POST or PUT carries the new resource here.جسم اختياري. طلب GET عادةً بلا جسم؛ أما POST أو PUT فيحمل المورد الجديد هنا.

Two headers appear on the slide. Host: localhost names the server. It looks redundant, since the client already connected to that machine, but one machine often hosts many websites on one IP address, and Host tells it which one you mean. RFC 9112 makes it mandatory: a client must send Host, and a server must answer 400 Bad Request to an HTTP/1.1 request without it. Accept: text/html says what kind of content the client would like back, here an HTML page. A JSON API client would send Accept: application/json.

تظهر ترويستان في الشريحة. Host: localhost تسمّي الخادم. تبدو زائدة، لأن العميل اتصل بذلك الجهاز أصلًا، لكن جهازًا واحدًا كثيرًا ما يستضيف مواقع عديدة على عنوان IP واحد، وHost تخبره أيها تقصد. ويجعلها RFC 9112 إلزامية: يجب على العميل إرسال Host، ويجب على الخادم أن يرد بـ 400 Bad Request على أي طلب HTTP/1.1 يخلو منها. Accept: text/html تقول نوع المحتوى الذي يود العميل استلامه، وهو هنا صفحة HTML. وعميل API يتعامل بـ JSON سيرسل Accept: application/json.

Route and resource: the lecturer's vocabularyالمسار (route) والمورد (resource): مفردات المحاضر

Slide 11 labels the / as the "HTTP route (root)" and index.html as the "resource". Use those words in this course: the route is where on the server you are going, and the resource is the thing you get. In part 01 a Route was defined as a method plus a path, so GET together with /index.html is one route.

تسمّي الشريحة 11 الرمز / بـ "HTTP route (root)" وindex.html بـ "resource". استخدم هذه الكلمات في هذا المقرر: الـ route هو المكان الذي تذهب إليه على الخادم، والـ resource هو الشيء الذي تحصل عليه. في الجزء 01 عُرِّف الـ route على أنه طريقة زائد مسار، لذا فإن GET مع /index.html يشكّلان route واحدًا.

You can watch a real request yourself. The verbose flag of curl prints what it sends and receives:

يمكنك مشاهدة طلب حقيقي بنفسك. خيار الإسهاب (verbose) في curl يطبع ما يرسله وما يستقبله:

curl -v http://localhost/index.html
> GET /index.html HTTP/1.1
> Host: localhost
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: text/html
< Content-Length: 500
<
<html> ... </html>

The server found index.html. Its reply has the same shape as the request: a first line, header fields, an empty line, then the body. Only the first line is different.

وجد الخادم index.html. ورده له شكل الطلب نفسه: سطر أول، ثم حقول ترويسة، ثم سطر فارغ، ثم الجسم. السطر الأول وحده هو المختلف.

The status lineسطر الحالة (status line)

A response starts with a Status line: HTTP/1.1 200 OK. It has three parts: the version, the Status code 200, and the status message OK, which the standard calls the reason phrase. Programs act on the number; the phrase is for humans and clients should not rely on it.

تبدأ الاستجابة بـ status line: HTTP/1.1 200 OK. وله ثلاثة أجزاء: الإصدار، وstatus code وهو 200، ورسالة الحالة OK التي يسمّيها المعيار reason phrase. البرامج تتصرف بناءً على الرقم؛ أما العبارة فهي للبشر، ويجب ألا يعتمد عليها العملاء.

The first digit of the code is its class, and the class alone tells you who is responsible. RFC 9110 defines five, and every valid code lies between 100 and 599 (slide 24 returns to this range).

الرقم الأول من الرمز هو فئته، والفئة وحدها تخبرك من المسؤول. يعرّف RFC 9110 خمس فئات، وكل رمز صالح يقع بين 100 و599 (تعود الشريحة 24 إلى هذا النطاق).

A useful pairing with the CRUD table: a successful GET answers 200 OK, a successful POST usually answers 201 Created, and asking for a lamp that does not exist answers 404 Not Found.

ربط مفيد مع جدول CRUD: طلب GET الناجح يُرد عليه بـ 200 OK، وطلب POST الناجح يُرد عليه عادةً بـ 201 Created، وطلب مصباح غير موجود يُرد عليه بـ 404 Not Found.

The headers describe the bodyالترويسات تصف الجسم

The two response headers on slide 12 tell the client how to read what follows. The Content-Type header, text/html, says the body is an HTML page, so the browser renders it instead of showing raw text. The Content-Length header, 500, says the Message body is exactly 500 bytes long, so the client knows when it has received all of it.

ترويستا الاستجابة في الشريحة 12 تخبران العميل كيف يقرأ ما يليهما. ترويسة Content-Type، وقيمتها text/html، تقول إن الجسم صفحة HTML، فيعرضها المتصفح بدلًا من إظهار نص خام. وترويسة Content-Length، وقيمتها 500، تقول إن الـ message body طوله 500 bytes بالضبط، فيعرف العميل متى استلمه كله.

The empty line the slide leaves outالسطر الفارغ الذي تُغفله الشريحة

Slide 12 draws a gap between Header and Body but never says what is in the gap. It is an empty line: a CRLF with nothing before it. The receiver reads line by line, and the moment it meets an empty line it knows the header section has ended. Everything after it is body, and Content-Length tells it how many bytes of body to read.

ترسم الشريحة 12 فجوة بين Header وBody لكنها لا تقول أبدًا ما الذي في الفجوة. إنه سطر فارغ: CRLF لا يسبقه شيء. المستقبِل يقرأ سطرًا سطرًا، وفي اللحظة التي يصادف فيها سطرًا فارغًا يعرف أن قسم الترويسات انتهى. كل ما بعده جسم، وContent-Length تخبره كم بايتًا من الجسم عليه أن يقرأ.