كيفية إنشاء عناوين URL REST بدون أفعال؟

StackOverflow https://stackoverflow.com/questions/1619152

  •  06-07-2019
  •  | 
  •  

سؤال

أجد صعوبة في تحديد كيفية تصميم عناوين URL مريحة.أنا أؤيد تمامًا النهج المريح المتمثل في استخدام عناوين URL مع الأسماء وليس الأفعال، ولا أفهم كيفية القيام بذلك.

نحن نقوم بإنشاء خدمة لتنفيذ الآلة الحاسبة المالية.تأخذ الآلة الحاسبة مجموعة من المعلمات التي سنقوم بتحميلها عبر ملف CSV.ستشمل حالات الاستخدام ما يلي:

  1. تحميل معلمات جديدة
  2. احصل على أحدث المعلمات
  3. الحصول على المعلمات لتاريخ عمل معين
  4. جعل مجموعة من المعلمات نشطة
  5. التحقق من صحة مجموعة من المعلمات

أعتقد أن النهج المريح هو الحصول على عناوين URL من النوع التالي:

/parameters
/parameters/12-23-2009

يمكنك تحقيق حالات الاستخدام الثلاث الأولى من خلال:

  1. POST حيث تقوم بتضمين ملف المعلمة في طلب النشر
  2. الحصول على عنوان URL الأول
  3. الحصول على عنوان URL الثاني

ولكن كيف يمكنك تنفيذ حالة الاستخدام الرابعة والخامسة بدون فعل؟ألن تحتاج إلى عناوين URL مثل:

/parameters/ID/activate
/parameters/ID/validate

??

هل كانت مفيدة؟

المحلول

ربما شيء مثل:

PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }

نصائح أخرى

المبادئ العامة لتصميم URI الجيد:

  • لا استخدم معلمات الاستعلام لتغيير الحالة
  • لا استخدم مسارات الحالة المختلطة إذا كان بإمكانك مساعدتها؛الأحرف الصغيرة هي الأفضل
  • لا استخدم الامتدادات الخاصة بالتنفيذ في عناوين URI الخاصة بك (.php، .py، .pl، وما إلى ذلك)
  • لا سقط في RPC مع عناوين URI الخاصة بك
  • يفعل الحد من مساحة URI الخاصة بك قدر الإمكان
  • يفعل إبقاء أجزاء المسار قصيرة
  • يفعل تفضل إما /resource أو /resource/;قم بإنشاء عمليات إعادة التوجيه 301 من تلك التي لا تستخدمها
  • يفعل استخدام معلمات الاستعلام للاختيار الفرعي للمورد؛أي.ترقيم الصفحات، استعلامات البحث
  • يفعل انقل العناصر من URI التي يجب أن تكون في رأس أو نص HTTP

(ملحوظة:لم أقل "تصميم URI مريح"؛معرفات URI غير شفافة بشكل أساسي في REST.)

المبادئ العامة لاختيار طريقة HTTP:

  • لا استخدم GET لتغيير الحالة؛هذه طريقة رائعة لجعل Googlebot يفسد يومك
  • لا استخدم PUT إلا إذا كنت تقوم بتحديث مورد بأكمله
  • لا استخدم PUT ما لم يكن بإمكانك أيضًا إجراء GET بشكل شرعي على نفس URI
  • لا استخدم POST لاسترداد المعلومات طويلة الأمد أو التي قد يكون من المعقول تخزينها مؤقتًا
  • لا إجراء عملية ليست كذلك عاجز مع وضع
  • يفعل استخدم GET لأكبر قدر ممكن
  • يفعل استخدم POST بدلاً من PUT عندما تكون في شك
  • يفعل استخدم POST عندما يتعين عليك القيام بشيء يشبه RPC
  • يفعل استخدم PUT لفئات الموارد الأكبر حجمًا أو ذات التسلسل الهرمي
  • يفعل استخدم DELETE بدلاً من POST لإزالة الموارد
  • يفعل استخدم GET لأشياء مثل العمليات الحسابية، ما لم تكن مدخلاتك كبيرة، ففي هذه الحالة استخدم POST

المبادئ العامة لتصميم خدمة الويب باستخدام HTTP:

  • لا وضع البيانات الوصفية في نص الرد الذي يجب أن يكون في الرأس
  • لا وضع بيانات التعريف في مورد منفصل ما لم يؤدي تضمينها إلى إنشاء حمل كبير
  • يفعل استخدم رمز الحالة المناسب
    • 201 Created بعد إنشاء المورد؛الموارد يجب موجودة في وقت إرسال الرد
    • 202 Accepted بعد إجراء عملية بنجاح أو إنشاء مورد بشكل غير متزامن
    • 400 Bad Request عندما يقوم شخص ما بإجراء عملية على بيانات من الواضح أنها زائفة؛بالنسبة لتطبيقك، قد يكون هذا خطأ في التحقق من الصحة؛احتفظ بشكل عام بـ 500 للاستثناءات التي لم يتم اكتشافها
    • 401 Unauthorized عندما يصل شخص ما إلى واجهة برمجة التطبيقات (API) الخاصة بك إما دون توفير معلومات ضرورية Authorization رأس أو عندما تكون بيانات الاعتماد داخل Authorization غير صالحة؛لا تستخدم رمز الاستجابة هذا إذا كنت لا تتوقع بيانات الاعتماد عبر Authorization header.
    • 403 Forbidden عندما يصل شخص ما إلى واجهة برمجة التطبيقات (API) الخاصة بك بطريقة قد تكون ضارة أو إذا لم يكن مصرحًا له بذلك
    • 405 Method Not Allowed عندما يستخدم شخص ما POST عندما كان يجب عليه استخدام PUT، وما إلى ذلك
    • 413 Request Entity Too Large عندما يحاول شخص ما إرسال ملف كبير الحجم بشكل غير مقبول إليك
    • 418 I'm a teapot عند محاولة تحضير القهوة باستخدام إبريق الشاي
  • يفعل استخدم رؤوس التخزين المؤقت كلما استطعت
    • ETag تكون الرؤوس جيدة عندما يمكنك بسهولة تقليل المورد إلى قيمة تجزئة
    • Last-Modified يجب أن يشير لك إلى أن الاحتفاظ بالطابع الزمني لوقت تحديث الموارد يعد فكرة جيدة
    • Cache-Control و Expires يجب أن تعطى قيم معقولة
  • يفعل كل ما تستطيعه لتكريم رؤوس التخزين المؤقت في الطلب (If-None-Modified, If-Modified-Since)
  • يفعل استخدم عمليات إعادة التوجيه عندما يكون ذلك منطقيًا، ولكن يجب أن تكون هذه نادرة بالنسبة لخدمة الويب

فيما يتعلق بسؤالك المحدد، يجب استخدام POST للرقمين 4 و5.تندرج هذه العمليات ضمن الإرشادات "المشابهة لـ RPC" أعلاه.بالنسبة لرقم 5، تذكر أنه ليس من الضروري استخدام POST Content-Type: application/x-www-form-urlencoded.يمكن أن يكون هذا بسهولة حمولة JSON أو CSV.

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

ولكن فقط مما كتبته أود أن أقول إن طلبك به مشاكل أكبر بكثير.

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

ما الذي تمثله "المعلمة" بالضبط؟من المحتمل أن يكون هناك عدد من الأشياء المختلفة، ويجب أن يكون لكل منها مورد منفصل مخصص لها.

هناك طريقة أخرى لتحقيق ذلك - عندما تناقش تطبيقك مع المستخدمين النهائيين (أولئك الذين يفترض أنهم لا يعرفون سوى القليل عن البرمجة)، ما هي الكلمات التي يستخدمونها بشكل متكرر؟

هذه هي الكلمات التي يجب أن تصمم تطبيقك حولها.

إذا لم تكن قد حصلت بعد على هذا التحويل مع المستخدمين المحتملين - أوقف كل شيء الآن ولا تكتب سطرًا آخر من التعليمات البرمجية حتى تفعل ذلك!عندها فقط سيكون لدى فريقك فكرة عما يجب بناؤه.

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

هناك عدد من الكتب الجيدة حول هذا الجزء من عملية تصميم البرمجيات.اثنان يمكنني أن أوصي بهما تصميم يحركه المجال و أنماط التحليل.

لا علاقة لتصميم عناوين URL الخاصة بك بما إذا كان تطبيقك RESTful أم لا.وبالتالي فإن عبارة "RESTful URLs" هي عبارة عن هراء.

أعتقد أنه يجب عليك القيام بمزيد من القراءة حول ماهية REST في الواقع.يتعامل REST مع عناوين URL على أنها مبهمة، وبالتالي لا يعرف ما بداخلها، سواء كانت أفعالًا أو أسماء أو أي شيء آخر.ربما لا تزال ترغب في تصميم عناوين URL الخاصة بك، ولكن هذا يتعلق بواجهة المستخدم، وليس REST.

ومع ذلك، دعنا نصل إلى سؤالك:الحالتان الأخيرتان غير مريحتين، ولا تتناسبان مع أي نوع من المخططات المريحة.هؤلاء هم ما يمكن أن نسميه RPC.إذا كنت جادًا بشأن REST، فسيتعين عليك إعادة التفكير في كيفية عمل تطبيقك من الألف إلى الياء.إما ذلك، أو التخلي عن REST وتنفيذ تطبيقك كتطبيق RPC.

هرممم ربما لا.

الفكرة هنا هي أنه يتعين عليك التعامل مع كل شيء كمورد، لذلك بمجرد أن تحتوي مجموعة من المعلمات على عنوان URL يمكنك الرجوع إليه منه، ما عليك سوى إضافة

الحصول على [parametersurl]/validationresults

مشاركة [paramatersurl]

جسم:{الأمر:"تفعيل"}

ولكن مرة أخرى، هذا الشيء المنشط هو RPC، وليس REST.

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

على سبيل المثالإنشاء بعض الموارد مثل،

/ActiveParameters
/ValidatedParameters

إذا كنت تريد تنشيط مجموعة من المعلمات، فقم بإضافة هذه المجموعة إلى مجموعة ActiveParameters.يمكنك إما تمرير مجموعة المعلمات كنص كيان، أو يمكنك تمرير عنوان url كمعلمة استعلام، كما يلي:

POST /ActiveParameters?parameter=/Parameters/{Id}

يمكن فعل الشيء نفسه باستخدام /ValidatedParameters.إذا كانت المعلمات غير صالحة، فيمكن للخادم إرجاع "طلب غير صالح" إلى طلب إضافة المعلمات إلى مجموعة المعلمات التي تم التحقق من صحتها.

أود أن أقترح الموارد والأساليب الوصفية التالية.

جعل المعلمات نشطة و/أو التحقق من صحتها:

> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<

تحقق مما إذا كانت المعلمات نشطة وصالحة:

> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
<     'active': true,
<     'require-valid': true,
<     'valid': {'status': false, 'reason': '...'}
< }
<

في بيئة REST، يعد كل عنوان URL موردًا فريدًا.ما هي الموارد الخاصة بك؟الآلة الحاسبة المالية لا تحتوي حقًا على أي موارد واضحة.تحتاج إلى البحث في ما تسميه المعلمات وسحب الموارد.على سبيل المثال، قد يكون تقويم استهلاك القرض أحد الموارد.قد يتضمن عنوان URL الخاص بالتقويم تاريخ البدء، والمدة (بالشهور أو السنوات)، والفترة (عندما تكون الفائدة مركبة)، وسعر الفائدة، والمبدأ الأولي.مع كل هذه القيم لديك تقويم محدد للمدفوعات:

http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000

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

يحرر: في الواقع كان من الممكن أن يمنع URI GET طلبات من البقاء العاجزين.

ومع ذلك، للتحقق من الصحة، فإن استخدام رموز حالة HTTP للإخطار بصلاحية الطلب (لإنشاء "معلمة" جديدة أو تعديل "معلمة" موجودة) سوف يتناسب مع نموذج Restful.

تقرير العودة مع أ 400 Bad Request رمز الحالة إذا كانت البيانات المقدمة غير صالحة ويجب تعديل الطلب قبل إعادة تقديمه (رموز الحالة HTTP/1.1).

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

مرخصة بموجب: CC-BY-SA مع الإسناد
لا تنتمي إلى StackOverflow
scroll top