web services فهم REST: الأفعال ، رموز الخطأ ، والمصادقة




web-services (8)

أنا أبحث عن طريقة لبرمجة واجهات برمجة التطبيقات حول الوظائف الافتراضية في تطبيقات الويب وقواعد البيانات و CMS.

لقد نظرت حولي ووجدت العديد من أطر "الهيكل العظمي". بالإضافة إلى الإجابات في سؤالي ، هناك Tonic ، وهو إطار REST أحب لأنه خفيف جدا.

أحب REST الأفضل لبساطتها ، ونود إنشاء بنية واجهة برمجة تطبيقات تعتمد عليها. أحاول أن أضع رأسي حول المبادئ الأساسية ولم أفهمها بالكامل بعد. لذلك ، هناك عدد من الأسئلة.

1. هل أنا أفهم ذلك صحيح؟

قل لدي مورد "المستخدمين". يمكنني إعداد عدد من عناوين URI على النحو التالي:

/api/users     when called with GET, lists users
/api/users     when called with POST, creates user record
/api/users/1   when called with GET, shows user record
               when called with PUT, updates user record
               when called with DELETE, deletes user record

هل هذا تمثيل صحيح لعمارة RESTful حتى الآن؟

2. أحتاج المزيد من الأفعال

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

بعض ما يتبادر إلى الذهن في مثال المستخدم هي:

activate_login
deactivate_login
change_password
add_credit

كيف أعبّر عن إجراءات مثل تلك الموجودة في بنية RESTful URL؟

ستكون غريزتي هي إجراء مكالمة GET إلى عنوان URL مثل

/api/users/1/activate_login 

وتوقع رمز الحالة مرة أخرى.

هذا ينحرف عن فكرة استخدام أفعال HTTP ، رغم ذلك. ما رأيك؟

3. كيفية إرجاع رسائل الخطأ والرموز

ينبع جزء كبير من جمال REST من استخدامه لطرق HTTP القياسية. على خطأ ، أبعث رأس مع رمز حالة خطأ 3xx أو 4xx أو 5xx. للحصول على وصف تفصيلي للخطأ ، يمكنني استخدام النص (صحيح؟). حتى الان جيدة جدا. ولكن ما هي الطريقة لنقل رمز خطأ خاص بالملكية أكثر تفصيلاً في وصف الخطأ الذي حدث (مثل "فشل الاتصال بقاعدة البيانات" ، أو "تسجيل الدخول إلى قاعدة بيانات خاطئة")؟ إذا وضعت في الجسم مع الرسالة ، لا بد لي من تحليلها بعد ذلك. هل هناك عنوان قياسي لهذا النوع من الأشياء؟

4. كيف نفعل المصادقة

  • كيف تبدو مصادقة أساس واجهة برمجة التطبيقات التي تتبع مبادئ REST؟
  • هل هناك نقاط قوية ضد استخدام الجلسات عند مصادقة عميل REST ، بخلاف أنه انتهاك صارخ لمبدأ REST؟ :) (فقط نصف المزاح هنا ، المصادقة المستندة إلى الجلسات ستلعب بشكل جيد مع البنية التحتية الحالية.)

ببساطة ، أنت تفعل هذا إلى الوراء بالكامل.

يجب ألا تقترب من عناوين URL التي يجب أن تستخدمها. ستأتي عناوين URL بشكل فعال "مجانًا" بمجرد تحديد الموارد اللازمة لنظامك وكيف ستُمثّل هذه الموارد والتفاعلات بين الموارد وحالة التطبيق.

اقتبس روي فيلدينغ

يجب أن تقضي واجهة برمجة التطبيقات (REST API) تقريبًا كل جهدها الوصفي في تعريف نوع (أنواع) الوسائط المستخدمة في تمثيل الموارد ودالة التطبيق ، أو في تعريف أسماء العلاقات الموسعة و / أو ترميز تمكين النص التشعبي لأنواع الوسائط القياسية الحالية. أي جهد يتم بذله لوصف الطرق المستخدمة في ما يتعلق بـ URIs ذات الأهمية يجب أن يتم تعريفها بالكامل في نطاق قواعد المعالجة لنوع الوسائط (وفي معظم الحالات ، تم تعريفها بالفعل بواسطة أنواع الوسائط الموجودة). [الفشل هنا يعني أن المعلومات خارج النطاق تقود التفاعل بدلاً من النص التشعبي.]

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

لنكون صادقين ، يرى العديد من حفنة من URIs وبعض GETs و PUTs و POSTs واعتقد REST أمر سهل. REST ليست سهلة. يعد RPC عبر HTTP أمرًا سهلاً ، حيث يسهل نقل النقط من البيانات ذهابًا وإيابًا عبر البروتوكولات عبر HTTP. REST ، ومع ذلك ، يتجاوز ذلك. REST هو بروتوكول الملحد. HTTP هو مجرد شعبية جدا وملائم لأنظمة REST.

يعيش REST في أنواع وسائل الإعلام ، وتعريفاتها ، وكيف يدفع التطبيق الإجراءات المتاحة لتلك الموارد عبر النص التشعبي (الروابط ، بشكل فعال).

هناك وجهة نظر مختلفة حول أنواع الوسائط في أنظمة REST. يفضل البعض استخدام الحمولات الصافية الخاصة بالتطبيقات ، بينما يحبذ البعض الآخر رفع أنواع الوسائط الموجودة إلى الأدوار المناسبة للتطبيق. على سبيل المثال ، من ناحية ، لديك مخططات XML محددة مصممة لتناسب تطبيقك مقابل استخدام شيء مثل XHTML كتصميمك ، ربما من خلال تنسيقات microformat والآليات الأخرى.

كلتا الطريقتين لديهما مكانهما ، كما أعتقد ، أن لغة XHTML تعمل جيدًا في السيناريوهات التي تتداخل مع كلٍّ من الويب المدفوع بالأنسان والمدفوعة بالآلات ، في حين أن أنواع البيانات السابقة والأكثر تحديدًا التي أشعر أنها تسهل التفاعل بين الماكينات والآلات بشكل أفضل. أجد أن الارتقاء بصيغ السلع الأساسية يمكن أن يجعل التفاوض على المحتوى أمرًا صعبًا. "application / xml + yourresource" أكثر تحديدًا كنوع وسائط أكثر من "application / xhtml + xml" ، حيث يمكن أن ينطبق هذا الأخير على العديد من الحمولات التي قد تكون أو لا تكون شيئًا ما يهتم به العميل الآلي ، ولا تحديد دون الاستبطان.

ومع ذلك ، يعمل XHTML بشكل جيد (بشكل واضح) في شبكة الإنترنت حيث تكون متصفحات الويب والتقديم مهمة للغاية.

سوف يرشدك التطبيق في مثل هذه القرارات.

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

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

على سبيل المثال ، قد يكون لديك:

<link href="http://example.com/users" rel="users" type="application/xml+usercollection"/>
<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>

ستتحدث وثائقك عن حقل rel بعنوان "users" ، ونوع الوسائط "application / xml + youruser".

قد تبدو هذه الوصلات زائدة عن الحاجة ، وكلها تتحدث إلى نفس URI ، إلى حد كبير. لكنهم ليسوا كذلك.

هذا لأن علاقة "المستخدمين" ، هذا الارتباط يتحدث عن مجموعة المستخدمين ، ويمكنك استخدام واجهة موحدة للعمل مع المجموعة (GET لاسترداد كل منهم ، DELETE لحذف كل منهم ، وما إلى ذلك)

إذا كنت POST إلى عنوان URL هذا ، فستحتاج إلى تمرير مستند "application / xml + usercollection" ، والذي قد يحتوي فقط على نسخة مستخدم واحدة داخل المستند حتى تتمكن من إضافة المستخدم ، أو ربما ، لإضافة عدة مستخدمين على ذات مرة. ربما تقترح وثائقك أنه يمكنك ببساطة تمرير نوع مستخدم واحد ، بدلاً من المجموعة.

يمكنك معرفة ما يتطلبه التطبيق من أجل إجراء بحث ، كما هو محدد في ارتباط "البحث" ونوعه الوسيط. ستخبرك وثائق نوع وسائط البحث بكيفية تصرف هذا ، وما الذي تتوقعه كنتائج.

ومع ذلك ، فإن الوجبات الجاهزة هنا هي أن عناوين URI نفسها غير مهمة في الأساس. التطبيق هو السيطرة على URIs ، وليس للعملاء. أبعد من "نقاط دخول" قليلة ، يجب أن يعتمد عملاؤك على عناوين URI المقدمة من قبل التطبيق لعملها.

يحتاج العميل إلى معرفة كيفية التعامل مع أنواع الوسائط وتفسيرها ، ولكنه لا يحتاج إلى رعاية أين تذهب.

هذان الرابطان متطابقان دلاليًا في نظر العملاء:

<link href="http://example.com/users?search" rel="search" type="application/xml+usersearchcriteria"/>
<link href="http://example.com/AW163FH87SGV" rel="search" type="application/xml+usersearchcriteria"/>

لذلك ، ركز على مواردك. ركز على تحولات الحالة في التطبيق وكيفية تحقيق ذلك على أكمل وجه.


إعادة 1 : هذا يبدو جيدا حتى الآن. تذكر أن تقوم بإرجاع URI للمستخدم الذي تم إنشاؤه حديثًا في رأس "الموقع:" كجزء من الاستجابة لـ POST ، إلى جانب رمز الحالة "201 Created".

إعادة 2 : التنشيط عبر GET هو فكرة سيئة ، وفعل الفعل في URI هو رائحة تصميم. قد ترغب في إعادة نموذج على GET. في تطبيق ويب ، سيكون هذا نموذج HTML مع زر إرسال ؛ في حالة استخدام واجهة برمجة التطبيقات ، قد ترغب في عرض تمثيل يحتوي على معرف موارد منتظم للتطبيق لتفعيل الحساب. بالطبع يمكنك تضمين عنوان URL هذا في الاستجابة على POST لـ / المستخدمين أيضًا. سيضمن استخدام PUT أن طلبك هو idempotent ، بمعنى أنه يمكن إرساله بأمان مرة أخرى إذا لم يكن العميل متأكدًا من النجاح. بشكل عام ، فكر في الموارد التي يمكنك تحويل أفعالك إليها (نوع من "nounification of verbs"). اسأل نفسك عن الطريقة التي تتماشى معها بشكل أكبر مع إجراءاتك المحددة. على سبيل المثال change_password -> PUT؛ إلغاء التنشيط -> ربما يحذف؛ add_credit -> احتمال POST أو PUT. قم بتوجيه العميل إلى عناوين URI المناسبة من خلال تضمينها في تمثيلاتك.

إعادة 3. لا تخترع رموز الحالة الجديدة ، إلا إذا كنت تعتقد أنها عامة جدًا تستحق أن تكون موحدة عالميًا. حاول جاهدا استخدام رمز الحالة الأنسب المتاحة (اقرأ عن كل منهم في RFC 2616). تضمين معلومات إضافية في نص الاستجابة. إذا كنت حقاً متأكداً من أنك تريد اختراع رمز حالة جديد ، فكر مرة أخرى ؛ إذا كنت لا تزال تعتقد ذلك ، فتأكد من اختيار الفئة الصحيحة على الأقل (1xx -> موافق ، 2xx -> المعلومات ، 3xx -> إعادة التوجيه ؛ 4xx-> خطأ العميل ، 5xx -> خطأ في الخادم). هل ذكرت أن اختراع رموز الحالة الجديدة فكرة سيئة؟

إعادة 4. إذا كان بأي طريقة ممكنة ، استخدم إطار المصادقة المدمج في HTTP. تحقق من طريقة مصادقة Google في GData. بشكل عام ، لا تضع مفاتيح API في عناوين URI الخاصة بك. حاول تجنب الجلسات لتعزيز قابلية التوسع ودعم التخزين المؤقت - إذا اختلفت الاستجابة لطلب ما بسبب شيء حدث من قبل ، فعادة ما تعين نفسك على مثيل عملية خادم محدد. من الأفضل بكثير تحويل حالة جلسة العمل إلى حالة العميل (على سبيل المثال ، جعلها جزءًا من الطلبات اللاحقة) أو جعلها صريحةً بتحويلها إلى حالة مورد (خادم) ، أي إعطاء عنوان URI الخاص بها.


مطول ، ولكن تم نسخها من مواصفات أسلوب HTTP 1.1 على http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

9.3 الحصول على

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

تتغير دلالات طريقة GET إلى "GET شرطي" إذا كانت رسالة الطلب تتضمن If-Modified-Since أو If-Unmodified-Since أو If-Match أو If-None-Match أو حقل رأس If-Range. تطلب طريقة GET المشروطة نقل الكيان فقط في ظل الظروف الموضحة في حقل (حقول) الرأس المشروطة. يهدف أسلوب GET الشرطي إلى تقليل استخدام الشبكة غير الضروري من خلال السماح بالتحديث إلى العناصر المخزنة مؤقتًا دون الحاجة إلى طلبات متعددة أو نقل البيانات الموجودة بالفعل لدى العميل.

تتغير دلالات طريقة GET إلى "GET جزئي" إذا كانت رسالة الطلب تتضمن حقل رأس نطاق. تطلب طلبات GET جزئية نقل جزء من الكيان فقط ، كما هو موضح في القسم 14.35. تهدف طريقة GET الجزئية إلى تقليل استخدام الشبكة غير الضروري من خلال السماح باستكمال الكيانات التي تم استردادها جزئيًا دون نقل البيانات الموجودة بالفعل لدى العميل.

تكون الاستجابة لطلب GET قابلة للتخزين المؤقت فقط إذا كانت تفي بمتطلبات التخزين المؤقت لـ HTTP الموضح في القسم 13.

انظر القسم 15.1.3 لاعتبارات الأمان عند استخدامها للنماذج.

9.5 وظيفة

تُستخدم طريقة POST لطلب أن يقبل خادم الأصل الكيان المضمن في الطلب كجهة فرعية جديدة من الموارد المحددة بواسطة طلب-URI في سطر الطلب. تم تصميم POST للسماح بطريقة موحدة لتغطية الوظائف التالية:

  - Annotation of existing resources;
  - Posting a message to a bulletin board, newsgroup, mailing list,
    or similar group of articles;
  - Providing a block of data, such as the result of submitting a
    form, to a data-handling process;
  - Extending a database through an append operation.

يتم تحديد الوظيفة الفعلية التي يتم تنفيذها بواسطة طريقة POST بواسطة الخادم وعادةً ما تعتمد على طلب-URI. يكون الكيان المنشور مرتبطًا بـ URI بنفس الطريقة التي يخضع بها الملف إلى دليل يحتوي عليه ، أو مقالة إخبارية تابعة لمجموعة أخبار يتم نشرها ، أو أن السجل يخضع لقاعدة بيانات.

قد لا يؤدي الإجراء الذي يتم تنفيذه بواسطة أسلوب POST إلى مورد يمكن تعريفه بواسطة معرف موارد منتظم. في هذه الحالة ، إما 200 (OK) أو 204 (لا يوجد محتوى) هي حالة الاستجابة المناسبة ، اعتمادًا على ما إذا كانت الاستجابة تتضمن كيانًا يصف النتيجة أم لا.

إذا تم إنشاء مورد على خادم المصدر ، يجب أن تكون الاستجابة 201 (تم الإنشاء) وتحتوي على كيان يصف حالة الطلب ويشير إلى المورد الجديد ورأسية الموقع (انظر القسم 14.30).

الردود على هذه الطريقة غير قابلة للتخزين المؤقت ، ما لم تتضمن الاستجابة حقول رأسية Cache-Control أو Expires مناسبة. ومع ذلك ، يمكن استخدام استجابة 303 (انظر غير ذلك) لتوجيه وكيل المستخدم لاسترداد مورد قابل للتخزين المؤقت.

يجب أن تخضع طلبات POST لمتطلبات إرسال الرسائل المنصوص عليها في القسم 8.2.

انظر القسم 15.1.3 لاعتبارات الأمان.

9.6

تطلب طريقة PUT أن يتم تخزين الكيان المرفق تحت عنوان URI المطلوب. إذا كان Request-URI يشير إلى مورد موجود بالفعل ، فيجب اعتبار الكيان المرفق كإصدار معدل للواحد المقيم على خادم المصدر. إذا لم يوجه طلب-URI إلى مورد موجود ، وأن معرف URI قادر على أن يتم تعريفه كمورد جديد بواسطة وكيل المستخدم المطالب ، يمكن لخادم الأصل إنشاء المورد باستخدام ذلك URI. إذا تم إنشاء مورد جديد ، فيجب على خادم المصدر إعلام وكيل المستخدم عبر استجابة 201 (تم الإنشاء). إذا تم تعديل مورد موجود ، فيجب إرسال رمز الاستجابة 200 (OK) أو 204 (بدون محتوى) للإشارة إلى إكمال الطلب بنجاح. If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem. The recipient of the entity MUST NOT ignore any Content-* (eg Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,

it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.

A single resource MAY be identified by many different URIs. For example, an article might have a URI for identifying "the current version" which is separate from the URI identifying each particular version. In this case, a PUT request on a general URI might result in several other URIs being defined by the origin server.

HTTP/1.1 does not define how a PUT method affects the state of an origin server.

PUT requests MUST obey the message transmission requirements set out in section 8.2.

Unless otherwise specified for a particular entity-header, the entity-headers in the PUT request SHOULD be applied to the resource created or modified by the PUT.

9.7 DELETE

The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.


أود أن أقترح (كتصريح أول) أنه يجب استخدام PUT فقط لتحديث الكيانات الحالية. يجب استخدام POST لإنشاء أخرى جديدة. أي

/api/users     when called with PUT, creates user record

لا يشعر بالحق بي. وباستطاعة باقي القسم الأول (إعادة استخدام الفعل) تبدو منطقية.


للحصول على الأمثلة التي ذكرتها ، سأستخدم ما يلي:

activate_login

POST /users/1/activation

deactivate_login

DELETE /users/1/activation

تغيير كلمة السر

PUT /passwords (يفترض هذا أن المستخدم موثق)

إضافة رصيد

POST /credits (يفترض هذا أن المستخدم موثق)

بالنسبة إلى الأخطاء ، يمكنك إرجاع الخطأ في النص بالتنسيق الذي حصلت عليه ، لذا إذا تلقيت:

DELETE /users/1.xml

كنت سترسل الرد مرة أخرى في XML ، وينطبق الشيء نفسه على JSON الخ ...

للمصادقة يجب عليك استخدام المصادقة المتشعب.


About REST return codes: it is wrong to mix HTTP protocol codes and REST results.

However, I saw many implementations mixing them, and many developers may not agree with me.

HTTP return codes are related to the HTTP Request itself. A REST call is done using a Hypertext Transfer Protocol request and it works at a lower level than invoked REST method itself. REST is a concept/approach, and its output is a business/logical result, while HTTP result code is a transport one.

For example, returning "404 Not found" when you call /users/ is confuse, because it may mean:

  • URI is wrong (HTTP)
  • No users are found (REST)

"403 Forbidden/Access Denied" may mean:

  • Special permission needed. Browsers can handle it by asking the user/password. (HTTP)
  • Wrong access permissions configured on the server. (HTTP)
  • You need to be authenticated (REST)

And the list may continue with '500 Server error" (an Apache/Nginx HTTP thrown error or a business constraint error in REST) or other HTTP errors etc...

From the code, it's hard to understand what was the failure reason, a HTTP (transport) failure or a REST (logical) failure.

If the HTTP request physically was performed successfully it should always return 200 code, regardless is the record(s) found or not. Because URI resource is found and was handled by the http server. Yes, it may return an empty set. Is it possible to receive an empty web-page with 200 as http result, right?

Instead of this you may return 200 HTTP code and simply a JSON with an empty array/object, or to use a bool result/success flag to inform about the performed operation status.

Also, some internet providers may intercept your requests and return you a 404 http code. This does not means that your data are not found, but it's something wrong at transport level.

From Wiki :

In July 2004, the UK telecom provider BT Group deployed the Cleanfeed content blocking system, which returns a 404 error to any request for content identified as potentially illegal by the Internet Watch Foundation. Other ISPs return a HTTP 403 "forbidden" error in the same circumstances. The practice of employing fake 404 errors as a means to conceal censorship has also been reported in Thailand and Tunisia. In Tunisia, where censorship was severe before the 2011 revolution, people became aware of the nature of the fake 404 errors and created an imaginary character named "Ammar 404" who represents "the invisible censor".


  1. استخدم النشر عندما لا تعرف كيف سيبدو URI المورد الجديد (تقوم بإنشاء مستخدم جديد ، سيقوم التطبيق بتعيين المستخدم الجديد له) ، PUT لتحديث أو إنشاء موارد تعرف كيف سيتم تمثيلها (مثال : PUT /myfiles/thisismynewfile.txt)
  2. إرجاع وصف الخطأ في نص الرسالة
  3. يمكنك استخدام مصادقة HTTP (إذا كانت كافية) يجب أن تكون خدمات الويب stateles

1. كنت قد حصلت على الفكرة الصحيحة حول كيفية تصميم الموارد الخاصة بك ، IMHO. لن أغير شيئًا.

2. بدلاً من محاولة توسيع نطاق HTTP بأكثر الأفعال ، فكر في ما يمكن تقليله من أفعالك المقترحة من حيث أساليب وموارد HTTP الأساسية. على سبيل المثال ، بدلاً من الفعل activate_login ، يمكنك إعداد موارد مثل: /api/users/1/login/active وهو منطقي بسيط. لتنشيط تسجيل دخول ، فقط PUT مستندًا هناك "صحيح" أو 1 أو أيًا كان. لإلغاء التنشيط ، PUT مستندًا فارغًا أو يقول 0 أو خطأ.

وبالمثل ، لتغيير أو تعيين كلمات المرور ، قم فقط بـ PUT s إلى /api/users/1/password .

كلما كنت بحاجة إلى إضافة شيء ما (مثل الائتمان) فكر في شروط POST s. على سبيل المثال ، يمكنك إجراء POST إلى مورد مثل /api/users/1/credits مع هيئة تحتوي على عدد الأرصدة المراد إضافتها. يمكن استخدام PUT على نفس المورد للكتابة فوق القيمة بدلاً من إضافة. سيتم طرح POST مع رقم سالب في الجسم ، وهكذا.

3. أنصح بشدة بعدم تمديد رموز حالة HTTP الأساسية. إذا لم تتمكن من العثور على واحد يطابق حالتك تمامًا ، فاختر أقرب واحد منك وضع تفاصيل الخطأ في نص الاستجابة. وتذكر أيضًا أن رؤوس HTTP قابلة للتوسعة ؛ يمكن للتطبيق تحديد جميع العناوين المخصصة التي تعجبك. أحد التطبيقات التي عملت عليها ، على سبيل المثال ، يمكن أن يعرض 404 Not Found تحت ظروف متعددة. بدلاً من جعل العميل يقوم بتحليل هيئة الاستجابة للسبب ، قمنا فقط بإضافة رأس جديد ، X-Status-Extended ، والذي يحتوي على امتدادات كود الحالة الخاصة بنا. لذلك قد ترى استجابة مثل:

HTTP/1.1 404 Not Found    
X-Status-Extended: 404.3 More Specific Error Here

وبهذه الطريقة ، سيظل عميل HTTP مثل متصفح الويب يعرف ما يجب فعله باستخدام رمز 404 العادي ، ويمكن لعميل HTTP أكثر تطوراً أن يختار عرض رأس X-Status-Extended لمزيد من المعلومات المحددة.

4. للمصادقة ، أوصي باستخدام مصادقة HTTP إذا استطعت. ولكن IMHO لا يوجد شيء خاطئ في استخدام المصادقة المستندة إلى ملفات تعريف الارتباط إذا كان ذلك أسهل بالنسبة لك.





rest