REST: the style and its six constraintsREST: الأسلوب وقيوده الستة

Picture two teams building a lamp API. One sends GET /getLampStatus?id=123 and POST /doSetBrightness, keeps a login session in server memory, and returns a different JSON shape from every endpoint. The other uses /lamps/123 for the lamp, changes it with standard methods, and puts everything the server needs into each request. Both speak HTTP. Only the second one is following REST.

تخيّل فريقين يبنيان واجهة API لمصباح. الفريق الأول يرسل GET /getLampStatus?id=123 وPOST /doSetBrightness، ويحتفظ بجلسة تسجيل الدخول في ذاكرة الخادم، ويعيد شكلًا مختلفًا منJSON من كل نقطة نهاية. والفريق الثاني يستخدم /lamps/123 للدلالة على المصباح، ويغيّره بالطرق القياسية، ويضع في كل طلب كل ما يحتاجه الخادم. كلا الفريقين يتحدث HTTP، لكن الثاني وحده يتبع REST.

The difference is not the protocol, which is the same, but the design discipline. REST stands for REpresentational State Transfer. Roy Thomas Fielding introduced it in his doctoral dissertation at the University of California, Irvine, in 2000, as a description of the principles that had guided the design of the Web itself.

الفرق ليس في البروتوكول (protocol)، فهو نفسه لدى الفريقين، بل في الانضباط التصميمي. REST اختصار لـ REpresentational State Transfer، أي "نقل الحالة التمثيلية". قدّمه Roy Thomas Fielding في أطروحة الدكتوراه الخاصة به في جامعة كاليفورنيا، إرفاين (University of California, Irvine) عام 2000، وصفًا للمبادئ التي وجّهت تصميم الويب نفسه.

REST is an architectural style: a named set of constraints on how the components of a system may interact. A protocol fixes message formats, field names and the order of exchanges. A style fixes none of that; it says things like "the server must not remember the client between requests" and leaves the bytes to whatever protocol you choose. REST then leverages HTTP to build scalable, stateless APIs, because HTTP already has what the constraints ask for: URLs to name resources, a fixed set of methods, status codes, caching headers and media types.

REST هو أسلوب معماري (architectural style): أي مجموعة مسمّاة من القيود على الطريقة التي يُسمح بها لمكونات النظام أن تتفاعل. البروتوكول يحدد صيغ الرسائل وأسماء الحقول وترتيب التبادلات. أما الأسلوب فلا يحدد شيئًا من ذلك، بل يقول أشياء مثل "يجب ألا يتذكر الخادم العميل بين طلب وآخر"، ويترك البايتات لأي بروتوكول تختاره. ثم يستفيد REST من HTTP لبناء واجهات API قابلة للتوسع وعديمة الحالة، لأن HTTP يملك أصلًا ما تطلبه هذه القيود: عناوين URL لتسمية الموارد، ومجموعة ثابتة من الطرق، ورموز الحالة، وترويسات التخزين المؤقت، وأنواع الوسائط (media types).

Statelessness, stated preciselyانعدام الحالة بتعريف دقيق

The slide singles out one constraint before listing the others, because it is the one most people get wrong. Statelessness has two halves, and an exam answer needs both:

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

1. The server does not store client session data between requests.لا يخزّن الخادم بيانات جلسة العميل (session data) بين الطلبات.
2. Every request must contain all the information necessary to process it.يجب أن يحتوي كل طلب على كل المعلومات اللازمة لمعالجته.

The two halves are the same rule seen from each side. If the server keeps nothing, the request must bring everything: which lamp, who is asking, and what change is wanted. Note what the server is allowed to keep: the lamp's own state, its brightness and power, is resource state and lives on the server. What it may not keep is conversation state, such as "this client logged in five minutes ago and was looking at lamp 123".

الشقّان هما القاعدة نفسها منظورًا إليها من كل جانب. إذا كان الخادم لا يحتفظ بشيء، فيجب أن يحمل الطلب كل شيء: أي مصباح، ومن يسأل، وما التغيير المطلوب. لاحظ ما يُسمح للخادم بالاحتفاظ به: حالة المصباح نفسه، أي سطوعه وتشغيله، هي حالة المورد (resource state) وتعيش على الخادم. أما ما لا يجوز له الاحتفاظ به فهو حالة المحادثة (conversation state)، مثل "هذا العميل سجّل دخوله قبل خمس دقائق وكان ينظر إلى المصباح 123".

REST defines six architectural constraints: five mandatory and one optional. Fielding builds them up one at a time, each added constraint buying a property the Web needed. Here is the whole map before we walk through it; hover to see the lamp example on each card.

يعرّف REST ستة قيود معمارية (architectural constraints): خمسة إلزامية وواحد اختياري. يبنيها Fielding قيدًا بعد قيد، وكل قيد يُضاف يكسب خاصية كان الويب يحتاج إليها. إليك الخريطة كاملة قبل أن نمرّ عليها واحدًا واحدًا، ومرّر المؤشر لترى مثال المصباح على كل بطاقة.

1. Client-server: split the jobs1. العميل والخادم (Client-server): تقسيم المهام

A mobile app shows a slider and a power button. A server holds the truth about lamp 123: is it on, how bright is it. The app never touches the lamp directly; it asks the server through the REST API. That is the client-server constraint: separation of client and server responsibilities. The client owns the user interface, the server owns the data and its state.

تطبيق جوال يعرض شريط تمرير وزر تشغيل. والخادم يحتفظ بالحقيقة عن المصباح 123: هل هو مضاء، وكم سطوعه. التطبيق لا يلمس المصباح مباشرة أبدًا، بل يسأل الخادم عبر واجهة REST API. هذا هو قيد العميل والخادم (client-server constraint): الفصل بين مسؤوليات العميل ومسؤوليات الخادم. العميل يملك واجهة المستخدم، والخادم يملك البيانات وحالتها.

The payoff is independent evolution. You can ship an iPhone app, an Android app and a web dashboard against the same server, or rewrite the server in a new language, without changing the others, as long as the interface between them holds.

والمكسب هو التطور المستقل لكل طرف. يمكنك إطلاق تطبيق iPhone وتطبيق Android ولوحة تحكم على الويب تتعامل كلها مع الخادم نفسه، أو إعادة كتابة الخادم بلغة جديدة، دون تغيير البقية، ما دامت الواجهة بينهما ثابتة.

2. Statelessness: every request stands alone2. انعدام الحالة (Statelessness): كل طلب قائم بذاته

Now the app sends three requests in a row: read lamp 123, dim it to 80, read it again. Under statelessness each of those requests carries the lamp ID and the required authentication, and none of them relies on the request before it. The server answers each one as if it had never seen this client.

الآن يرسل التطبيق ثلاثة طلبات متتالية: اقرأ المصباح 123، ثم خفّض سطوعه إلى 80، ثم اقرأه مرة أخرى. في ظل انعدام الحالة يحمل كل طلب من هذه الطلبات معرّف المصباح والمصادقة المطلوبة، ولا يعتمد أي منها على الطلب الذي قبله. ويجيب الخادم عن كل طلب كأنه لم يرَ هذا العميل من قبل.

That is why the constraint exists. Fielding lists three gains: visibility (a monitor can understand a request by looking at that request alone), reliability (recovering from a partial failure is easy) and scalability (the server frees resources right after each request). In cloud terms the third one is the big one: if no server holds your session, a load balancer can send your next request to any of ten identical servers, and you scale by adding servers. The cost is that every request repeats some data, such as the token, which adds a few bytes to each message.

ولهذا وُجد هذا القيد. يذكر Fielding ثلاثة مكاسب: الوضوح (visibility)، إذ يستطيع نظام المراقبة فهم الطلب بالنظر إليه وحده؛ والموثوقية (reliability)، إذ يسهل التعافي من عطل جزئي؛ وقابلية التوسع (scalability)، إذ يحرر الخادم موارده فور انتهاء كل طلب. وبمصطلحات السحابة فإن المكسب الثالث هو الأهم: إذا لم يكن أي خادم يحتفظ بجلستك، يستطيع موازن الأحمال (load balancer) أن يرسل طلبك التالي إلى أي خادم من عشرة خوادم متطابقة، فتتوسع بإضافة خوادم. والثمن أن كل طلب يكرر بعض البيانات، مثل الرمز (token)، مما يضيف بضعة بايتات إلى كل رسالة.

3. Cacheability: let responses be reused3. قابلية التخزين المؤقت (Cacheability): اسمح بإعادة استخدام الاستجابات

Lamp status does not change every millisecond. If a dashboard refreshes every few seconds, sending each refresh all the way to the server is waste. Cacheability says that responses must indicate whether they can be cached and reused. In HTTP that label is the Cache-Control header. When the server returns Cache-Control: max-age=60, it allows the lamp information to be reused for 60 s. A response that must never be reused, such as a one-time token, says so with no-store.

حالة المصباح لا تتغير كل جزء من الثانية. فإذا كانت لوحة التحكم تتحدّث كل بضع ثوانٍ، فإن إرسال كل تحديث حتى الخادم هدر. تنص قابلية التخزين المؤقت (Cacheability) على أن الاستجابات يجب أن توضّح هل يمكن تخزينها مؤقتًا وإعادة استخدامها أم لا. وفي HTTP هذه العلامة هي الترويسة Cache-Control. فعندما يعيد الخادم Cache-Control: max-age=60، فهو يسمح بإعادة استخدام معلومات المصباح لمدة 60 s. والاستجابة التي يجب ألا يُعاد استخدامها أبدًا، مثل رمز يُستخدم مرة واحدة، تصرّح بذلك عبر no-store.

You want lamp 123 at 80 percent brightness. Under REST the app sends PATCH /lamps/123 with the header Content-Type: application/json and the body {"brightness": 80}. The response describes the lamp and includes links for what you can do next. That one exchange already demonstrates all four parts of the next constraint.

تريد أن يكون سطوع المصباح 123 عند 80 بالمئة. في REST يرسل التطبيق PATCH /lamps/123 مع الترويسة Content-Type: application/json والجسم {"brightness": 80}. وتصف الاستجابة المصباح وتتضمن روابط لما يمكنك فعله بعد ذلك. هذا التبادل الواحد يوضّح وحده الأجزاء الأربعة كلها للقيد التالي.

4. Uniform interface: one way to talk to every resource4. الواجهة الموحدة (Uniform interface): طريقة واحدة للتعامل مع كل مورد

The uniform interface means standardized interaction with resources. Every resource is handled with the same small set of moves, so a client that knows how to talk to lamps also knows how to talk to users or thermostats. It has four sub-constraints:

الواجهة الموحدة (uniform interface) تعني تفاعلًا موحدًا قياسيًا مع الموارد. يُتعامل مع كل مورد بالمجموعة الصغيرة نفسها من الحركات، فالعميل الذي يعرف كيف يتعامل مع المصابيح يعرف أيضًا كيف يتعامل مع المستخدمين أو منظمات الحرارة. ولها أربعة قيود فرعية:

1. Resource identification through URIs. Each resource has a URI: /lamps/123 uniquely identifies lamp 123.تعريف الموارد عبر عناوين URI. لكل مورد (resource) عنوان URI: فالعنوان /lamps/123 يعرّف المصباح 123 تعريفًا فريدًا.
2. Manipulation through representations. The client never touches the lamp object; it sends a representation of the desired state. PATCH /lamps/123 with {"brightness": 80} updates the brightness. PATCH applies a partial change, unlike PUT which replaces the whole resource.التعديل عبر التمثيلات. العميل لا يلمس كائن المصباح أبدًا، بل يرسل تمثيلًا (representation) للحالة المرغوبة. فالطلب PATCH /lamps/123 مع {"brightness": 80} يحدّث السطوع. والطريقة PATCH تطبّق تغييرًا جزئيًا، بخلاف PUT التي تستبدل المورد كاملًا.
3. Self-descriptive messages. Each message carries enough to be understood alone. The method PATCH, the header Content-Type: application/json and the JSON body together describe the requested update; that is a self-descriptive message.رسائل تصف نفسها بنفسها. كل رسالة تحمل ما يكفي لفهمها وحدها. فالطريقة PATCH، والترويسة Content-Type: application/json، وجسم JSON، تصف معًا التحديث المطلوب؛ وهذه هي الرسالة ذاتية الوصف (self-descriptive message).
4. Hypermedia as the engine of application state (HATEOAS). The lamp's response includes links or actions to retrieve, update or delete the lamp, so the client discovers what it can do next from the response instead of from hard-coded URLs.الوسائط التشعبية بوصفها محرّك حالة التطبيق (HATEOAS). تتضمن استجابة المصباح روابط أو إجراءات لجلب المصباح أو تحديثه أو حذفه، فيكتشف العميل ما يمكنه فعله بعد ذلك من الاستجابة نفسها بدلًا من عناوين URL مكتوبة مسبقًا في الشيفرة.

5. Layered system: the client sees only the next hop5. النظام الطبقي (Layered system): العميل لا يرى إلا الطبقة التالية

A lamp request rarely goes straight to one server. It passes through an API gateway that checks the token and rate limits, then a load balancer that picks a healthy server, before reaching the smart-home servers. A layered system supports such intermediary layers, including proxies, gateways and load balancers. In Fielding's words, each component cannot see beyond the immediate layer it is interacting with.

نادرًا ما يذهب طلب المصباح مباشرة إلى خادم واحد. فهو يمر عبر بوابة API (API gateway) تتحقق من الرمز وتطبّق حدود معدّل الطلبات (rate limits)، ثم عبر موازن أحمال يختار خادمًا سليمًا، قبل أن يصل إلى خوادم المنزل الذكي. والنظام الطبقي (layered system) يدعم مثل هذه الطبقات الوسيطة، ومنها الخوادم الوسيطة (proxies) والبوابات وموازنات الأحمال. وبتعبير Fielding: لا يستطيع أي مكوّن أن يرى ما وراء الطبقة المباشرة التي يتفاعل معها.

This is where the constraints reinforce each other. Because requests are stateless, the load balancer can send each one anywhere. Because messages are self-descriptive and cacheable, a proxy in the middle can cache them without knowing anything about lamps. For the edge-to-cloud continuum this matters directly: a cache or gateway at the edge is just another layer the client never has to know about.

هنا تعزّز القيود بعضها بعضًا. فلأن الطلبات عديمة الحالة، يستطيع موازن الأحمال أن يرسل كل طلب إلى أي مكان. ولأن الرسائل ذاتية الوصف وقابلة للتخزين المؤقت، يستطيع خادم وسيط في المنتصف أن يخزنها مؤقتًا دون أن يعرف أي شيء عن المصابيح. وهذا يهم مباشرة في سلسلة الحافة إلى السحابة (edge-to-cloud continuum): فالذاكرة المؤقتة أو البوابة الموجودة على الحافة (edge) ما هي إلا طبقة أخرى لا يحتاج العميل أبدًا إلى معرفتها.

6. Code on demand: the optional one6. الشيفرة عند الطلب (Code on demand): القيد الاختياري

The server sends JavaScript to the browser to provide an interactive lamp-control interface. That is code on demand: servers may provide executable code to clients, extending what the client can do after it is deployed. It is the only optional constraint, because it reduces visibility: an intermediary cannot easily tell what downloaded code will do.

يرسل الخادم شيفرة JavaScript إلى المتصفح ليقدّم واجهة تفاعلية للتحكم في المصباح. هذه هي الشيفرة عند الطلب (code on demand): يجوز للخوادم أن تزوّد العملاء بشيفرة قابلة للتنفيذ، فتوسّع ما يستطيع العميل فعله بعد نشره. وهي القيد الاختياري الوحيد، لأنها تقلل الوضوح (visibility): إذ لا يستطيع الوسيط أن يعرف بسهولة ما ستفعله الشيفرة التي جرى تنزيلها.

The constraints say what a REST API must respect. The slides then switch to practice: what you actually write down when designing one. Take "dim lamp 123 to 80" one last time and list every decision you had to make.

تحدد القيود ما يجب أن تلتزم به واجهة REST API. ثم تنتقل الشرائح إلى التطبيق العملي: ما الذي تكتبه فعلًا عندما تصمم واجهة كهذه. خذ "خفّض سطوع المصباح 123 إلى 80" مرة أخيرة، واسرد كل قرار كان عليك اتخاذه.

Those five rows are the REST design elements: URL, HTTP request method, HTTP response status code, header fields and JSON message. The next part uses exactly this list to design the full lamp API and a calculator API, so learn it now as a checklist.

هذه الصفوف الخمسة هي عناصر تصميم REST (REST design elements): URL، وطريقة طلب HTTP، ورمز حالة استجابة HTTP، وحقول الترويسة، ورسالة JSON. يستخدم الجزء التالي هذه القائمة بالضبط لتصميم واجهة المصباح كاملة وواجهة آلة حاسبة، لذا احفظها الآن كقائمة تحقق.

How the pieces map onto the constraintsكيف ترتبط هذه الأجزاء بالقيود

Every entity the system manages, whether a file, a user, a virtual machine or an IoT device, is treated as a resource, and each resource is uniquely identified by a URI such as /lamps/123. That is design element 1 and uniform-interface sub-constraint i.

كل كيان يديره النظام، سواء كان ملفًا أو مستخدمًا أو آلة افتراضية أو جهاز إنترنت أشياء (IoT)، يُعامل على أنه مورد (resource)، وكل مورد يُعرَّف تعريفًا فريدًا بعنوان URI مثل /lamps/123. هذا هو عنصر التصميم 1 والقيد الفرعي i للواجهة الموحدة.

A resource is represented in JSON, the format most REST APIs use. JSON represents resource data as key-value pairs, and those representations are exchanged in HTTP request and response bodies. That is design element 5 and sub-constraint ii. Its media type is application/json.

يُمثَّل المورد بصيغة JSON، وهي الصيغة التي تستخدمها معظم واجهات REST. تمثّل JSON بيانات المورد على شكل أزواج مفتاح وقيمة (key-value pairs)، وتُتبادل هذه التمثيلات داخل أجسام (bodies) طلبات HTTP واستجاباته. هذا هو عنصر التصميم 5 والقيد الفرعي ii. ونوع الوسائط الخاص بها هو application/json.

Additional information travels in header fields: an authentication token, the Content-Type of the body, and the response formats the client accepts (Accept). That is design element 4, and it is what makes messages self-descriptive.

تنتقل المعلومات الإضافية في حقول الترويسة (header fields): رمز المصادقة (authentication token)، وContent-Type الخاص بالجسم، وصيغ الاستجابة التي يقبلها العميل (Accept). هذا هو عنصر التصميم 4، وهو ما يجعل الرسائل ذاتية الوصف.

Finally, REST APIs follow stateless communication: each request contains the information the server needs to process it independently. That is why the token sits in a header of every request instead of in a server-side session.

وأخيرًا، تتبع واجهات REST تواصلًا عديم الحالة: كل طلب يحتوي على المعلومات التي يحتاجها الخادم لمعالجته باستقلال. ولهذا يوضع الرمز في ترويسة كل طلب بدلًا من حفظه في جلسة على جانب الخادم.