هل هذا بقية API حقا RPC؟ يبدو أن الميدان روي يعتقد ذلك
https://stackoverflow.com/questions/1164154
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russianسؤال
هناك كمية كبيرة من ما اعتقدت أنني كنت أعرف عن الراحة مخطئ على ما يبدو - وأنا لست وحدي. هذا السؤال له رصاص طويل، ولكن يبدو أنه ضروري لأن المعلومات مبعثرة بعض الشيء. يأتي السؤال الفعلي في النهاية إذا كنت على دراية بهذا الموضوع بالفعل.
من الفقرة الأولى من Fealling Roy يجب أن يكون راحة واجهات برمجة التطبيقات النصية, ، من الواضح جدا أنه يعتقد أن عمله يسيء تفسيره على نطاق واسع:
أشعر بالإحباط من عدد الأشخاص الذين يدعون أي واجهة تستند إلى HTTP API راحة. مثال اليوم هو الراحة SocialSite API.. وبعد هذا هو rpc. يصرخ RPC. هناك اقتران كبير جدا على عرض أنه يجب إعطاء تصنيف X.
الميدان يذهب إلى قائمة العديد من سمات API الراحة. يبدو أن البعض منهم يتعارضون على كل من الممارسة المشتركة والمشورة المشتركة بشأن المنتديات وغيرها من المنتديات. علي سبيل المثال:
يجب إدخال API الراحة مع عدم وجود معرفة مسبقة خارج URI الأولي (إشارة مرجعية) ومجموعة من أنواع الوسائط الموحدة المناسبة للجمهور المقصود (أي، من المتوقع أن يفهمها أي عميل قد يستخدم API). ...
يجب عدم تحديد API الراحة أسماء الموارد الثابتة أو التسلسلات الهرمية (اقتران واضح للعميل والخادم). ...
يجب أن يقض API الراحة في جميع جهودها الوصفية تقريبا في تحديد نوع (أنواع) الوسائط المستخدمة في تمثيل الموارد ودولة تطبيق القيادة، أو في تحديد أسماء العلاقات الممتدة و / أو العلامات التشعبي التي تم تدعمها التشعبية لأنواع الوسائط القياسية الحالية. ...
تلعب فكرة "النص التشعبي" دورا رئيسيا - أكثر من مجرد هيكل URI أو ما يعنيه أفعال HTTP. يتم تعريف "النص التشعبي" في أحد التعليقات:
عندما أقول [Fielding] النص التشعبي، أعني العرض التقديمي المتزامن للمعلومات والضوابط بحيث تصبح المعلومات هي التأكد من خلالها المستخدم (أو Automaton) يحصل على خيارات وتحديد الإجراءات. HyperMedia هو مجرد توسيع حول النص يعني إدراج المراسين الزمنية داخل دفق وسائل الإعلام؛ انخفض معظم الباحثين التمييز.
لا يحتاج النص التشعبي إلى أن يكون HTML على متصفح. يمكن أن تتبع الأجهزة الروابط عندما يفهمون تنسيق البيانات وأنواع العلاقات.
أعتقد في هذه المرحلة، ولكن يبدو أن أول نقطتين أعلاه تشير إلى أن وثائق API لمورد فو الذي يشبه ما يلي يؤدي إلى ضيق اقتران بين العميل والخادم وليس لديه مكان في نظام مريح.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
بدلا من ذلك، يجب إجبار وكيل على اكتشاف URIS لجميع FOOS بواسطة، على سبيل المثال، إصدار طلب الحصول ضد / فيووس. (قد تتحول تلك الأوريس إلى اتباع النمط أعلاه، ولكن هذا بجانب النقطة.) يستخدم الاستجابة نوع وسائط قادر على نقل كيفية الوصول إلى كل عنصر وما الذي يمكن القيام به معه، مما أدى إلى النقطة الثالثة أعلاه وبعد لهذا السبب، يجب أن تركز وثائق API على شرح كيفية تفسير النص التشعبي الموجود في الاستجابة.
علاوة على ذلك، في كل مرة يطلب فيها uri على مورد فو، يحتوي الاستجابة على جميع المعلومات اللازمة لكيل لاكتشاف كيفية المتابعة، على سبيل المثال، الوصول إلى الموارد المرتبطة والوائية من خلال URIS، أو عن طريق اتخاذ إجراءات بعد الإبداع / حذف مورد.
مفتاح النظام بأكمله هو أن الاستجابة تتكون من النص التشعبي الموجود في نوع الوسائط الذي ينقل نفسه إلى خيارات الوكيل للمتابعة. انها ليست على عكس الطريقة التي يعمل بها المتصفح للبشر.
ولكن هذا هو مجرد تخمين أفضل في هذه اللحظة بالذات.
أرسلت الميدان أ متابعة واستجاب فيها للنقد بأن مناقشته كانت مجردة للغاية، تفتقر إلى أمثلة، غارغون غني:
سيحاول الآخرون فك ما كتبته بطرق أكثر مباشرة أو قابلة للتطبيق على بعض الاهتمام العملي اليوم. ربما لن أكون، لأنني مشغول جدا بالموضوع التالي، والتحضير لعقد مؤتمر، أو يكتب معيارا آخر، أو السفر إلى مكان بعيد، أو مجرد القيام بالأشياء الصغيرة التي سمحت لي أن أشعر أنني حصلت على راتبتي.
لذلك، سؤالان بسيطان لخبراء الباقي هناك بعقلية عملية: كيف تفسر الميدان القول وكيف تضعها موضع التنفيذ عند توثيق / تنفيذ برية برامج أبيس؟
تحرير: هذا السؤال هو مثال على مدى صعوبة تعلم شيء ما إذا لم يكن لديك اسم لما تتحدث عنه. الاسم في هذه الحالة هو "Hypermedia كمحرك حالة التطبيق" (HESTOAS).
المحلول
أعتقد أن تفسيرك يغطيها في الغالب. URIS هي معرفات معتمية يجب توصيلها، بالنسبة للجزء الأكبر، إلى أبعد من المرجعية URI المستخدمة من قبل وكيل المستخدم للوصول إلى التطبيق.
أما بالنسبة للتوثيق، فقد تم هذا السؤال عدة مرات. تقوم بتوثيق نوع الوسائط الخاص بك، بالإضافة إلى عناصر تحكم الارتباط التشعبي الذي يحتوي عليه (روابط وأشكال)، ونموذج التفاعل إذا كنت ترغب في ذلك (انظر Atompub).
إذا قمت بتوثيق URIS أو كيفية بناءها، فأنت تفعل ذلك خطأ.
نصائح أخرى
تفسيرك يبدو صحيحا بالنسبة لي. أعتقد أن قيود الميدان يمكن تطبيقها عمليا.
أود حقا أن أرى شخصا ما نشر بعض الأمثلة الجيدة لكيفية توثيق واجهة الراحة. هناك العديد من الأمثلة السيئة، لديها بعض منها ساري المفعول لإشارة المستخدمين إلى أن تكون ذات قيمة للغاية.
لقد كنت أبحث عن مثال جيد على واجهة برمجة التطبيقية المكتوبة بعد القاطرة واجهت مشكلة في العثور على واحدة (وجدت كل من SunCloud API وأشياء Atompub يصعب تطبيقها على وضع API "الطبيعي"). لذلك حاولت تقديم مثال واقعي على مدونتي التي أعقبت نصيحة Felse Roy حول ما يعنيه تنفيذ بقية مناسبة. لقد وجدت أنه من الصعب للغاية التوصل إلى مثال، على الرغم من حقيقة أنه بسيط إلى حد ما من حيث المبدأ (مربك فقط عند العمل مع واجهة برمجة تطبيقية بدلا من صفحة ويب). أحصل على ما كان روي مؤخرا مع وتوافق عليه، إنه مجرد تحول في الذهن للتنفيذ بشكل صحيح ل API.
الق نظرة: مثال API باستخدام الراحة
الاستثناء الوحيد لإعطاء تعليمات حول كيفية إنشاء URIS هو أنه يجوز إرسال قالب URI في استجابة التشعبية، مع استبدال الحقول تلقائيا من قبل العميل، باستخدام حقول أخرى في النص التشعبي. لا ينتهي هذا عادة بحفظ الكثير من النطاق الترددي على الرغم من أن ضغط Gzip سيؤدي إلى التعامل مع الأجزاء المتكررة من URIS جيدا بما يكفي حتى لا تهتم بهذا.
بعض المناقشات الجيدة حول الراحة والاتواس ذات الصلة:
بالنسبة للمهتمين، وجدت مثالا مفصلا على HESTOAS في الممارسة في Sun Cloud API..
الشيء الذي يخطئ فيه معظم الناس هو أن (على الأقل أفكر) في العالم الباقي لا توثق "واجهة الراحة" الخاصة بك، ما تقوم بتوثيقه هو نوع الوسائط، بشكل مستقل عن الخادم أو الخدمة.
صحيح تماما. أود بالإضافة إلى ذلك أن قوالب URI هي بخير تماما ضمن تطبيق مريح طالما كانت الأنماط من المستندات المستلمة من الخادم (OpenSearch كونها مثال مناسب). بالنسبة لقوالب URI، تقوم بتوثيق المكان الذي يتم فيه استخدامه وما هي العناصر النائبة المتوقعة في القالب، ولكن ليس القوالب نفسها. على عكس ما قاله الوحيدين، هذا ليس استثناء.
على سبيل المثال، في عملي، لدينا نظام داخلي لإدارة المجال، وتحتوي وثيقة الخدمة على قوالب URI: واحد لإنتاج أفضل تخمين URI لمورد المجال، وآخر لبناء URI لتوافر المجال. ما زال من الممكن الصفحة من خلال مجموعة المجالات لمعرفة ما هو URI المجال المعطى، ولكن بالنظر إلى العدد الهائل من المجالات التي تديرها، فلن يكون هذا ممكنا للعميل، لذلك منحهم وسيلة لتخمين ما قد يكون URI لمورد المجال فوزا كبيرا من حيث سهولة التنفيذ من وجهة نظر العميل، وعرض النطاق الترددي من الخادم.
فيما يتعلق بسؤالك: تعرض وثائقنا المعيارية الموارد، وتأثير الطرق المختلفة على هذه الموارد، وأنواع وسائل الإعلام التمثيل المستخدمة ومخططاتها، وأي نوع من الموارد التي تشير إليها URIS في تلك الممتنة.
كما نشمل وثائق غير معيارية (إعلامية) تعلق عليها إخلاء المسؤولية بعدم قراءتها كثيرا في URIS المذكورة في المستند، مما يوفر أمثلة على تفاعلات خادم العميل النموذجية. هذا يضع الوثائق المعيارية مجردة إلى حد ما بشروط ملموسة.
أفكر في عدد السنوات التي كانت الراحة هناك الآن، وقد حان التقنيات مع مفهوم المورد وما هو حقا أو غير مريح.
وفقا لنموذج استحقاق ريتشاردسون، هناك 4 مستويات (0-3) تحدد مدى راحة واجهة برمجة التطبيقات الخاصة بك، مع 3 تعني واجهة برمجة تطبيقية مريحة حقا، تماما كما أقصد ميدان روي.
المستوى 0 هو عندما يكون لديك نقطة إدخال واحدة URI - مثل الصابون.
المستوى 1 يعني أن API قادرا على التمييز بين موارد مختلفة، ولديها أكثر من نقاط دخول واحدة - لا تزال تنبعث منها الصابون.
المستوى 2 هو عند استخدام أفعال HTTP - احصل على، مشاركة، حذف في المقام الأول. هذا هو المستوى الذي يأتي به الباقي حقا في الصورة.
في المستوى 3، تبدأ في استخدام عناصر تحكم HyperMedia لجعل API الخاص بك حقا مريح.
الروابط المقترحة لمزيد من القراءة:
لنفرض GET /foos/createForm يتم استدعاء للحصول على قيم الحقول التي يجب توفيرها عندما نذهب لإنشاء POST /foos وبعد الآن هذا هو عنوان URL الخاص أي 1 المستخدمة لإنشاء فيوين يجب ذكرها في الاستجابة GET /foos/createForm كوصلة عمل تقديم وفقا لاقتراح الميدان، أليس كذلك؟
ثم الفائدة من إجراءات التعيين على أفعال HTTP المعروفة إلى الإجراءات "الاتفاقية عبر الكود / التكوين" يتم إلغاء شيء.
