تصميم API ويب RESTful

مقالة
03/29/2023

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

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

يصف هذا الدليل المشكلات التي يجب مراعاتها عند تصميم واجهة برمجة تطبيقات الويب.

ما المقصود بكلمة REST؟

في عام 2000، اقترح روي فيلدينغ انتقال الحالة التمثيلية (REST) كنهج معماري لتصميم خدمات الويب. REST تعتبر نمط معماري لبناء الأنظمة الموزعة تعتمد على وسائط hypermedia. REST مستقل عن أي بروتوكول نقل نص تشعبي ولا يرتبط بالضرورة ب HTTP. ومع ذلك تستخدم تطبيقات REST API الأكثر انتشارًا HTTP كبروتوكول للتطبيق، ويركز هذا الدليل على تصميم واجهات برمجة تطبيقات REST ل HTTP.

الميزة الأساسية ل REST عبر تطبيق HTTP هي أنها تستخدم معايير مفتوحة، ولا تربط تنفيذ واجهة برمجة التطبيقات أو تطبيقات العميل بأي تنفيذ محدد. يمكن على سبيل المثال كتابة خدمة ويب REST في ASP.NET، ويمكن لتطبيقات العميل استخدام أي لغة أو مجموعة أدوات يمكنها إنشاء طلبات HTTP وتحليل استجابات HTTP.

وتشمل فيما يلي بعض مبادئ التصميم الرئيسية لواجهات برمجة تطبيقات RESTful باستخدام HTTP:

تصمم واجهات برمجة تطبيقات RESTالخاصة بالموارد،التي تعتبر نوع من العناصر أو البيانات أو الخدمات التي يمكن للعميل الوصول إليها.
يحتوي المورد على معرف، وهو URI الذي يعرف هذا المورد بشكل فريد. يستخدم URI على سبيل المثال لطلب عميل معين:
```
https://adventure-works.com/orders/1
```
يتفاعل العملاء مع الخدمة من خلال تبادل تمثيلات الموارد. يستخدم الكثير من واجهات برمجة تطبيقات الويب JSON كتهيئة تبادل. يؤدي على سبيل المثال طلب GET إلى URI المذكور أعلاه إلى إرجاع نص الاستجابة هذا:
```
{"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}
```
تستخدم واجهات برمجة تطبيقات REST واجهة موحدة، وبالتالي يساعد هذا على فصل تطبيقات العميل والخدمة. بالنسبة لواجهات برمجة تطبيقات REST المبنية على HTTP، تتضمن الواجهة الموحدة استخدام أفعال HTTP القياسية لإجراء العمليات على الموارد. العمليات الأكثر انتشارًا هي GET وPOST و PUT و PATCH و DELETE.
تُستخدم واجهات برمجة تطبيقات REST نموذج طلب عديم الحالة. يجب أن تكون طلبات HTTP مستقلة وقد تحدث بأي ترتيب، لذا فإن الاحتفاظ بمعلومات الحالة العابرة بين الطلبات غير ممكن. المكان الوحيد الذي يتم فيه تخزين المعلومات تعتبر الموارد نفسها، ويجب أن يتوفر لـ كل طلب عملية ذرية. يوفر هذا القيد خدمات الويب أن تعتبر قابلة للتطوير بدرجة كبيرة، لأنه ليست هناك حاجة للاحتفاظ بأي ترابط بين العملاء وخوادم محددة. يتيح لأي خادم معالجة أي طلب من عميل ما. ربما تحد مع ذلك عوامل أخرى من قابلية التوسع. على سبيل المثال، تكتب العديد من خدمات الويب إلى مخزن بيانات الواجهة الخلفية، والذي قد يكون من الصعب توسيع نطاقه. لمزيد من المعلومات حول استراتيجيات توسيع نطاق مخزن البيانات، راجع تقسيم البيانات الأفقي والعمودي والوظيفي.
تعتمد واجهات برمجة تطبيقات REST على ارتباطات وسائط hypermedia المضمنة في التمثيل. يعرض على سبيل المثال ما يلي تمثيل JSON لأمر. يحتوي على روابط للحصول على العميل المرتبط بالطلب أو تحديثه.
```
{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links": [
    {"rel":"product","href":"https://adventure-works.com/customers/3", "action":"GET" },
    {"rel":"product","href":"https://adventure-works.com/customers/3", "action":"PUT" }
  ]
}
```

اقترح ليونارد ريتشاردسون في عام 2008 نموذج النضج التالي لواجهات برمجة تطبيقات الويب:

المستوى 0: حدد URI واحدًا، وجميع هذه العمليات هي طلبات POST إلى URI هذا.
المستوى الأول: أنشئ عناوين URL منفصلة للموارد الفردية.
المستوى الثاني: استخدم أساليب HTTP لتعريف العمليات على الموارد.
المستوى الثالث: استخدم hypermedia (HATEOAS، المذكورة أدناه).

يتوافق المستوى الثالث مع واجهة برمجة تطبيقات RESTful وفقًا لتعريف Fielding. توجد في الممارسة العملية عدة واجهات برمجة تطبيقات الويب المنشورة في مكان ما فيما يخص المستوى الثاني.

تنظيم تصميم واجهة برمجة التطبيقات فيما يخص الموارد

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

https://adventure-works.com/orders // Good

https://adventure-works.com/create-order // Avoid

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

غالبًا ما يتوفر تجميع الكيانات معًا في مجموعات (الطلبات والعملاء). المجموعة هي مورد منفصل عن العنصر داخل المجموعة، وينبغي أن يتوفر لها URI الخاص بها. ربما يمثل على سبيل المثال URI التالي مجموعة الطلبات:

https://adventure-works.com/orders

يؤدي إرسال طلب HTTP GET إلى URI للمجموعة إلى استرجاع قائمة بالعناصر في المجموعة. يحتوي كل عنصر في المجموعة على URI الفريد الخاص به. يقوم طلب HTTP GET إلى URI الخاص بالعنصر باسترداد تفاصيل ذلك العنصر.

استخدام اصطلاح تسمية متسق في معرفات URI. فإنه يساعد عامة على استخدام الأسماء الجمع لـ عناوين URL التي تشير إلى المجموعات. تنظيم عناوين URL للمجموعات والعناصر في تسلسل هرمي.من الممارسات الجيدة. على سبيل المثال، /customers هو المسار إلى مجموعة العملاء، و/customers/5 هو المسار إلى العميل بـ معرف يساوي 5. يساعد هذا الأسلوب في الحفاظ على سهولة استخدام واجهة برمجة تطبيقات الويب. يتوفر أيضًا لعدة أطر عمل واجهة برمجة تطبيقات الويب توجيه الطلبات بناءً على مسارات URI ذات المعلمات، حتى يتيح لك تحديد مسار للمسار /customers/{id}.

ضع في اعتبارك أيضًا العلاقات بين أنواع مختلفة من الموارد وكيف يتوفر لك كشف هذه الارتباطات. على سبيل المثال، /customers/5/orders ربما يمثل جميع الطلبات للعميل رقم 5. يتوفر لك أيضًا الانتقال في الاتجاه الآخر، وتمثيل الاقتران من طلب إلى عميل باستخدام URI مثل /orders/99/customer. ومع ذلك ربما يصبح توسيع هذا النموذج إلى حد بعيد مرهقًا في التنفيذ. الحل الأفضل توفير ارتباطات قابلة للتنقل إلى الموارد المقترنة في نص رسالة استجابة HTTP. توصف هذه الآلية بالتفصيل الكامل في قسم استخدام HATEOAS لتوفير التنقل إلى الموارد ذات الصلة.

في الأنظمة الأكثر تعقيدًا، ربما يصبح من المغري توفير معرفات URI التي توفر للعميل التنقل عبر مستويات متعددة من العلاقات، مثل /customers/1/orders/99/products. ومع ذلك يصبح من الصعب الحفاظ على هذا المستوى من التعقيد ويعتبر غير مرن إذا تغيرت العلاقات بين الموارد في المستقبل. بدلًا من ذلك حاول الحفاظ على URI سهلة نسبيًا. بمجرد أن يحتوي التطبيق على مرجع إلى مورد، يجب أن يستخدم هذا المرجع للعثور على العناصر المتعلقة بهذا المورد. يتاح استبدال الاستعلام السابق بـ URI /customers/1/orders للعثور على جميع الطلبات للعميل رقم 1، ثم /orders/99/products العثور على المنتجات بهذا الترتيب.

تلميح

تجنب طلب معرفات الموارد URI المعقدة من المجموعة/العنصر/المجموعة.

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

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

وأخيرًا ربما يصبح غير متوفرًا تعيين كل عملية تنفذها واجهة برمجة تطبيقات الويب إلى مورد معين. يتوفر لك معالجة مثل هذه السيناريوهات غير المتعلقة بالموارد من خلال طلبات HTTP التي تستدعي دالة وتعيد النتائج كرسالة استجابة HTTP. ربما توفر على سبيل المثال واجهة برمجة تطبيقات الويب التي تنفذ عمليات حاسبة بسيطة مثل الإضافة والطرح معرفات URI التي تعرض هذه العمليات كموارد مستعارة وتستخدم سلسلة الاستعلام لتحديد المعلمات المطلوبة. على سبيل المثال، قد يرجع طلب GET إلى URI /add?operand1=99&operand2=1 رسالة استجابة مع النص الأساسي الذي يحتوي على القيمة 100. واستخدم مع ذلك هذه الأشكال فقط من عناوين URI باعتدال.

تحديد عمليات واجهة برمجة التطبيقات من حيث أساليب HTTP

يحدد بروتوكول HTTP عددًا من الطرق التي تحدد معنى دلاليًا لطلب ما. أساليب HTTP الشائعة التي تستخدمها معظم واجهات برمجة تطبيقات الويب RESTful هي:

يسترجع GET تمثيل المورد في URI المحدد. يشتمل نص رسالة الاستجابة على تفاصيل المورد المطلوب.
ينشئ POST موردًا جديدًا في URI المعرف. يتحقق نص رسالة الطلب من توفير تفاصيل عن المورد الجديد. لاحظ أنه يتوفر لك أيضًا استخدام POST لتشغيل العمليات التي لا تنشئ الموارد بالفعل.
تقوم PUT بإنشاء المورد أو استبداله في URI المحدد. يحدد نص رسالة الطلب المورد الذي سوف يُنشئ أو يتحدث.
يُجري PATCH تحديث جزئي للمورد. يحدد نص الطلب مجموعة التغييرات التي سوف تطبق على المورد.
DELETE يزيل المورد في URI المحدد.

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

المورد	انشر	حصل	ضع	حذف
/العملاء	أنشئ عميلًا جديداً	استرد كل العملاء	تحديث مجمع للعملاء	أزل جميع العملاء
/customers/1	خطأ	استرد تفاصيل العميل رقم واحد	حدث تفاصيل العميل رقم واحد إذا وجد	أزل العميل رقم واحد
/customers/1/orders	أنشئ طلب جديد للعميل رقم واحد	استرد جميع الطلبات للعميل رقم واحد	حدث المجمع للطلبات الخاصة بالعميل رقم واحد	أزل جميع الطلبات الخاصة بالعميل رقم واحد

ربما تعد الاختلافات بين POST و PUT و PATCH محيرة.

ينشئ طلب ترحيل للمورد. يعين الخادم URI للمورد الجديد، ويرجع URI ذلك إلى العميل. في نموذج REST، يمكنك تطبيق طلبات POST بتكرار على المجموعات. يُضاف المورد الجديد إلى المجموعة. يستخدم أيضًا طلب POST لإرسال البيانات للمعالجة إلى مورد موجود بالفعل بدون إنشاء أي مورد جديد.
ينشئ طلب PUT موردًا أو يحدث موردًا موجودًا.بالفعل. يحدد العميل URI الخاص بالمورد. يشتمل نص الطلب على تمثيل كامل للمورد. في حالة وجود مورد يحتوي على URI هذا موجودا بالفعل، يستبدل المورد. وإلا ينشئ مورد جديد، إذا كان الخادم يدعم ذلك الأمر. تطبق طلبات PUT بتكرار على الموارد التي تعتبر عناصر فردية، مثل عميل معين، بدلا من المجموعات. يدعم الخادم التحديثات ولكن لا يدعم الإنشاء عبر PUT. يعتمد دعم الإنشاء من خلال PUT على قدرة العميل على تعيين URI إلى مورد قبل وجوده بشكل هادف. إذا لم يعد الأمر كما هو، فـ استخدم POST لإنشاء الموارد و PUT أو PATCH للتحديث.
يقوم طلب PATCH بإجراء تحديث جزئي لمورد موجود بالفعل. يحدد العميل URI الخاص بالمورد. يحدد نص الطلب مجموعة من التغييرات لتنفيذها على المورد. ربما يعتبر ذلك أكثر فاعلية من استخدام PUT، لأن العميل يرسل التغييرات فقط، وليس التمثيل الكامل للمورد. من الناحية الفنية يوفر لـ PATCH أيضا إنشاء مورد جديد (عن طريق تحديد مجموعة من التحديثات لمورد "خال")، إذا كان الخادم يدعم هذا.

ينبغي أن تكون طلبات PUT متكررة. إذا أرسل العميل نفس طلب PUT عدة مرات، ينبغي أن تكون النتائج دائما هي نفسها (سيتم تعديل نفس المورد بنفس القيم). طلبات POST و PATCH ليست مضمونة لتكون متكررة.

تتفق مع دلالات HTTP

يصف هذا القسم بعض الاعتبارات النموذجية لتصميم API تتوافق مع مواصفات HTTP. ومع ذلك فإنه لا يغطي كل التفاصيل أو السيناريوهات المحتملة. عند الشك في أمر ما راجع مواصفات HTTP.

أنواع الوسائط

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

في بروتوكول HTTP تحدد التنسيقات من خلال استخدام أنواع الوسائط، وتسمى أيضًا أنواع MIME. بالنسبة للبيانات غير الثنائية، تدعم معظم واجهات برمجة تطبيقات الويب JSON (نوع الوسائط = application/json) وربما XML (نوع الوسائط = application/xml).

يحدد العنوان الخاص بـ نوع المحتوى في طلب أو استجابة تنسيق التمثيل. فيما يلي مثال على طلب POST الذي يحتوي على بيانات JSON:

POST https://adventure-works.com/orders HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

إذا كان الخادم لا يدعم نوع الوسائط، فـ ينبغي أن يرجع رمز حالة HTTP 415 (نوع الوسائط غير المدعوم).

يحتوي طلب العميل على عنوان قبول يشتمل على قائمة بأنواع الوسائط التي سيقبلها العميل من الخادم في رسالة الاستجابة. على سبيل المثال:

GET https://adventure-works.com/orders/2 HTTP/1.1
Accept: application/json

إذا لم يتمكن الخادم من مطابقة أي من أنواع الوسائط المدرجة، فيجب أن يرجع رمز حالة HTTP 406 (غير مقبول).

قسم الأساليب

عادة ما تسترد طريقة GET الناجحة رمز حالة HTTP 200 (OK). إذا تعذر العثور على المورد، ينبغي أن يرجع الأسلوب 404 (غير موجود).

إذا تم استيفاء الطلب ولكن لا يوجد نص استجابة مضمن في استجابة HTTP، فيجب عليه إرجاع رمز حالة HTTP 204 (بلا محتوى)؛ على سبيل المثال، قد يتم تنفيذ عملية بحث لا تسفر عن أي تطابقات مع هذا السلوك.

أساليب خاصة بـ POST

إذا حاول أسلوب POST بإنشاء مورد جديد، فإنه يرجع رمز حالة HTTP 201 (تم إنشاؤه). يتضمن URI المورد الجديد في عنوان الموقع للاستجابة. يشتمل نص الاستجابة على تمثيل للمورد.

إذا كان الأسلوب يعالج بعض الأمور ولكنه لا ينشئ موردًا جديدًا، ربما يصبح للأسلوب إرجاع رمز حالة HTTP 200 وتضمين نتيجة العملية في نص الاستجابة. بدلاً من ذلك إذا لم توجد نتيجة لإرجاع، يصبح للأسلوب إرجاع رمز حالة HTTP 204 (بلا محتوى) دون نص استجابة.

إذا وضع العميل بيانات غير صالحة في الطلب، ينبغي على الخادم إرجاع رمز حالة HTTP 400 (طلب غير صالح). ربما يحتوي نص الاستجابة على معلومات إضافية حول الخطأ أو ارتباط إلى URI وذلك يوفر المزيد من التفاصيل.

أساليب خاصة بـ PUT

إذا أنشئ أسلوب PUT مورد جديد، فإنه يرجع رمز حالة HTTP 201 (أنشئ بالفعل)، كما هو الحال مع أسلوب POST. إذا كانت الطريقة تقوم بتحديث مورد موجود، فإنها ترجع 200 (موافق) أو 204 (بلا محتوى). في بعض الحالات، لا يصبح تحديث المورد موجود بالفعل. في هذا الأمر ضع في اعتبارك إرجاع رمز حالة HTTP 409 (تعارض).

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

أساليب خاصة بـ PATCH

مع طلب PATCH، يرسل العميل مجموعة من التحديثات إلى مورد موجود، في صورةمستند تصحيح. يعالج الخادم مستند التصحيح لتطبيق التحديث. لا يصف مستند التصحيح المورد بأكمله، بل مجموعة من التغييرات التي يجب تنفيذها فقط. لا تحدد مواصفات أسلوب PATCH (RFC 5789) تنسيقاً معيناً لمستندات التصحيح. يلزم استنتاج التنسيق من نوع الوسائط في الطلب.

ربما يكون JSON هو تنسيق البيانات الأكثر شيوعاً لـ API الويب. يوجد تنسيقان رئيسيان من تنسيقات التصحيح المستندة إلى JSON، تسمى تصحيح JSONوتصحيح دمج JSON.

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

افترض أن المورد الأصلي علي سبيل المثال، لديه تمثيل JSON التالي:

{
    "name":"gizmo",
    "category":"widgets",
    "color":"blue",
    "price":10
}

فيما يلي تصحيح دمج JSON ممكن لهذا المورد:

{
    "price":12,
    "color":null,
    "size":"small"
}

يخبر هذا الخادم بتحديث و priceحذفcolor وإضافةsize، بينما لم يتم تعديل name وcategory. لكي تحصل على تفاصيل دقيقة لتصحيح دمج JSON، فراجع RFC 7396. نوع الوسائط الخاصة بتصحيح دمج JSON هو application/merge-patch+json.

تصحيح الدمج غير مناسب إذا كان المورد الأصلي من الممكن أن يحتوي على قيم فارغة صريحة، بسبب المعنى null الخاص في مستند التصحيح. لا يحدد مستند التصحيح الترتيب الذي يلزم على الخادم تطبيق التحديثات به أيضاً. قد يكون ذلك مهمًا وقد لا يكون، اعتمادًا على البيانات والمجال. يعد تصحيح JSON، المحدد في RFC 6902، أكثر مرونة. تحدد التغييرات كسلسلة من العمليات المطلوب تطبيقها. تشمل العمليات الإضافة والإزالة والاستبدال والنسخ والاختبار (للتحقق من صحة القيم). يعد نوع الوسائط الخاصة بتصحيح دمج JSON هو application/json-patch+json.

فيما يلي بعض حالات الخطأ النموذجية التي ربما تتم مواجهتها عند معالجة طلب PATCH، جنبًا إلى جنب مع رمز حالة HTTP المناسب.

حالة خطأ	رمز حالة HTTP
تنسيق مستند التصحيح غير مدعوم.	415 (نوع وسائط غير مدعوم)
مستند تصحيح مشوه.	400 (طلب غير صحيح)
مستند التصحيح صالح، لكن لا يمكن تنفيذ التغييرات على المورد في حالته الحالية.	409 (تعارض)

طرق الحذف

في حالة نجاح عملية الحذف، يلزم أن يستجيب خادم الويب برمز حالة HTTP 204 (لا يوجد محتوى)، مشيرًا إلى أنه تم التعامل مع العملية بنجاح، لكن نص الاستجابة لا يحتوي على معلومات إضافية. في حالة عدم وجود المورد، يمكن لخادم الويب إرجاع HTTP 404 (غير موجود).

العمليات غير المتزامنة

في بعض الأحيان قد تتطلب عملية POST أو PUT أو PATCH أو DELETE معالجة قد تستغرق بعض الوقت لإكمالها. إذا انتظرت الإكمال قبل إرسال استجابة إلى العميل، فقد يتسبب ذلك في زمن انتقال غير مقبول. وإن كان الأمر كذلك، فخذ بعين الاعتبار في جعل العملية غير متزامنة. استرجاع حالة بروتوكول نقل نص تشعبي ذات التعليمة البرمجية 202 (مقبول) للإشارة إلى قبول الطلب للمعالجة ولكنه لم يكتمل.

يجب عليك أن تعرض نقطة النهاية التي تُرجع حالة الطلب غير المتزامن، حتى يتمكن العميل من مراقبة الحالة عن طريق التحقق من نقطة نهاية الحالة. أدخل URI لنقطة نهاية الحالة في عنوان الموقع لاستجابة 202. على سبيل المثال:

HTTP/1.1 202 Accepted
Location: /api/status/12345

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

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}

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

HTTP/1.1 303 See Other
Location: /api/orders/12345

لمزيد من المعلومات حول كيفية تنفيذ هذا الأسلوب، راجع توفير دعم غير متزامن للطلبات طويلة الأمد ونمط الطلب-الرد غير المتزامن.

مجموعات فارغة في أجسام الرسائل

في أي وقت يكون نص الاستجابة الناجحة فارغا، يجب أن يكون رمز الحالة 204 (بلا محتوى). بالنسبة إلى المجموعات الفارغة، مثل الاستجابة لطلب تمت تصفيته بدون عناصر، يجب أن يكون رمز الحالة 204 (بلا محتوى)، وليس 200 (موافق).

تصفية البيانات وترقيمها

يمكن أن يؤدي عرض مجموعة من الموارد من خلال URI واحد إلى إحضار التطبيقات لكميات كبيرة من البيانات عندما تكون مجموعة فرعية فقط من المعلومات مطلوبة. على سبيل المثال، لنفترض أن تطبيق العميل يحتاج إلى العثور على جميع الطلبات بتكلفة تتجاوز قيمة معينة. تُسترد جميع الطلبات من /orders URI ثم تصفية هذه الطلبات من جانب العميل. ومن الواضح لنا أن هذه العملية غير فعّالة للغاية. فإنها تهدر عرض النطاق الترددي للشبكة وقوة المعالجة على الخادم الذي يستضيف واجهة برمجة تطبيقات الويب.

فبدلًا من ذلك، يمكن أن تسمح واجهة برمجة التطبيقات بتمرير عامل تصفية في سلسلة الاستعلام من URI، مثل /orders?minCost=n. ثم تكون واجهة برمجة تطبيقات الويب مسؤولة عن تحليل المعلمة ومعالجتها minCost في سلسلة الاستعلام وإرجاع النتائج التي أُصفيت من جانب الخادم.

يمكن أن تسترجع طلبات GET عبر موارد المجموعة عددًا كبيرًا من العناصر. يلزمك تصميم واجهة برمجة تطبيقات الويب للحد من كمية البيانات التي تُسترجع بواسطة أي طلب فردي. ضع في عين الاعتبار دعم سلاسل الاستعلام التي تحدد الحد الأقصى لعدد العناصر المراد استردادها وإزاحة البداية إلى المجموعة. على سبيل المثال:

/orders?limit=25&offset=50

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

يمكنك استخدام استراتيجية مماثلة لفرز البيانات عند إحضارها، من خلال توفير معلمة فرز تأخذ اسم حقل باعتبارها قيمة، مثل /orders?sort=ProductID. ومع ذلك، يمكن أن يكون لهذا النهج تأثيرًا سلبيًا على التخزين المؤقت، لأن معلمات سلسلة الاستعلام تشكل جزءًا من معرّف المورد المستخدم من قبل العديد من تطبيقات ذاكرة التخزين المؤقت باعتبارها مفتاحًا للبيانات المخزنة مؤقتًا.

يمكنك توسيع هذا النهج للحد من الحقول التي اُسترجعت لكل عنصر، في حال إن كان كل عنصر يحتوي على كمية كبيرة من البيانات. على سبيل المثال، يمكنك استخدام معلمة سلسلة استعلام تقبل قائمة من الحقول مفصولة بفواصل، مثل /orders?fields=ProductID,Quantity.

امنح جميع المعلمات الاختيارية في سلاسل الاستعلام افتراضيات تحتوي علي معنى. على سبيل المثال، اضبط المعلمة limit إلى 10 والمعلمة offset إلى 0 في حال إن قمت بتنفيذ فصل الصفحات، واضبط معلمة الفرز إلى مفتاح المورد في حال إن قمت بتنفيذ الترتيب، وضبط المعلمة fields إلى كافة الحقول في المورد في حال إن كنت تدعم الإسقاطات.

ادعم الاستجابات الجزئية للموارد الثنائية الكبيرة

فقد يحتوي المورد على حقول ثنائية كبيرة، مثل الملفات أو الصور. للتغلب على المشاكل الناجمة عن الاتصالات غير الموثوق بها والمتقطعة ولتحسين أوقات الاستجابة، ضع في اعتبارك تمكين استرداد هذه الموارد في مجموعات. لفعل ذلك، يجب أن تدعم واجهة برمجة تطبيقات الويب عنوان Accept-Ranges لطلبات GET للموارد الكبيرة. يشير هذا العنوان إلى أن عمليات GET يمكنها دعم الطلبات الجزئية. يمكن لتطبيق العميل إرسال طلبات GET التي تسترجع مجموعة فرعية من مورد، محددة باعتبارها نطاقًا من وحدات البايت.

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

HEAD https://adventure-works.com/products/10?fields=productImage HTTP/1.1

فيما يلي مثال يوضح رسالة استجابة:

HTTP/1.1 200 OK

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

يشير عنوان طول المحتوى إلى الحجم الإجمالي للمورد، ويشير عنوان Accept-Ranges إلى أن عملية GET المقابلة تدعم النتائج الجزئية. كما يمكن لتطبيق العميل استخدام هذه المعلومات لاسترداد الصورة في مجموعات أصغر. يُحضر الطلب الأول أول 2500 بايت باستخدام عنوان النطاق:

GET https://adventure-works.com/products/10?fields=productImage HTTP/1.1
Range: bytes=0-2499

تشير رسالة الاستجابة إلى أن هذه استجابة جزئية عن طريق استرجاع حالة بروتوكول نقل نص تشعبي ذات التعليمة البرمجية 206. يحدد عنوان طول المحتوى العدد الفعلي لوحدات البايت التي اُسترجعت في نص الرسالة (وليس حجم المورد)، ويشير عنوان نطاق المحتوى والذي هو جزء من المورد إلى (بايت 0-2499 من أصل 4580):

HTTP/1.1 206 Partial Content

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580

[...]

يمكن لطلب لاحق من تطبيق العميل استرداد ما تبقى من المورد.

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

إشعار

لا توجد حاليًا معايير للأغراض العامة والتي تحدد كيفية نمذجة مبدأ HATEOAS. توضح الأمثلة المذكورة في هذا القسم أحد الحلول الممكنة والخاصة.

على سبيل المثال، للتعامل مع مؤشر العلاقة بين طلب وعميل، قد يتضمن تمثيل الطلب ارتباطات تحدد العمليات المتاحة لعميل الطلب. يُعرض فيما يلي أمثلة شاملة:

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"https://adventure-works.com/customers/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"customer",
      "href":"https://adventure-works.com/customers/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"https://adventure-works.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"https://adventure-works.com/orders/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"https://adventure-works.com/orders/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"https://adventure-works.com/orders/3",
      "action":"DELETE",
      "types":[]
    }]
}

في هذا المثال، تحتوي linksالمصفوفة على مجموعة من الروابط. يمثل كل ارتباط عملية على كيان ذات صلة. تشتمل بيانات كل ارتباط علي العلاقة ("العميل") و URI (https://adventure-works.com/customers/3) وأسلوب HTTP وأنواع MIME المدعومة. تعد هذه هي جميع المعلومات التي يحتاجها تطبيق العميل حتى يتمكن من استدعاء العملية.

تتضمن linksالمصفوفة أيضًا معلومات مرجعية ذاتية حول المورد نفسه الذي تم استرداده. والتي لها نفس العلاقة.

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

تعيين إصدار API ويب RESTful

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

يمكّن تعيين الإصدار API الويب للإشارة إلى الميزات والموارد التي تعرضها، ويمكن لتطبيق العميل إرسال الطلبات التي يتم توجيهها إلى إصدار معين من الميزة أو المورد. تصف الأقسام التالية عدة مناهج متنوعة، لكل منها فوائده ومقايضاته.

لا يوجد تعيين للإصدار

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

على سبيل المثال، يجب أن يرجع الطلب إلى URI https://adventure-works.com/customers/3 تفاصيل عميل واحد يحتوي على idو nameو address حقول متوقعة من قبل تطبيق العميل:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","address":"1 Microsoft Way Redmond WA 98053"}

إشعار

للتبسيط، لا تتضمن الاستجابات النموذجية الموضحة في هذا القسم روابط HATEOAS.

DateCreated إذا تمت إضافة الحقل إلى مخطط مورد العميل، فسوف تبدو الاستجابة كما يلي:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","dateCreated":"2014-09-04T12:11:38.0376089Z","address":"1 Microsoft Way Redmond WA 98053"}

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

تعيين إصدار خاص بـ URI

في كل مرة تقوم فيها بتعديل API الويب أو تغيير مخطط الموارد، يمكنك إضافة رقم إصدار إلى URI لكل مورد. يلزم أن تستمر معرفات URI الموجودة سابقاً في العمل كما كان من قبل، مع إرجاع الموارد التي تتوافق مع مخططها الأصلي.

توسيع المثال السابق، إذا address تم إعادة هيكلة الحقل إلى حقول فرعية تحتوي على كل جزء مكون من العنوان (مثل streetAddressو cityوstateوzipCode)، من الممكن عرض هذا الإصدار من المورد من خلال URI يحتوي على رقم إصدار، مثل https://adventure-works.com/v2/customers/3:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","dateCreated":"2014-09-04T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

تعد آلية تعيين الإصدار هذه بسيطة جداً ولكنها تعتمد على توجيه الخادم للطلب إلى نقطة النهاية المناسبة. ومع ذلك، من الممكن أن تصبح غير عملية مع نضوج API الويب من خلال العديد من التكرارات و يلزم على الخادم دعم عدد من الإصدارات المختلفة. من وجهة نظر المطهر أيضاً، في جميع الحالات تقوم تطبيقات العميل بإحضار نفس البيانات (العميل 3)، لذلك يلزم ألا يكون URI مختلفاً حقاً اعتماداً على الإصدار. ويعقد هذا المخطط أيضا تنفيذ نظام HATEOAS حيث سوف تحتاج جميع الروابط إلى تضمين رقم الإصدار في عناوين URL الخاصة بها.

تعيين إصدارات سلسلة الاستعلام

بدلا من توفير URIs متعددة، يمكنك أن تحدد إصدار المورد باستخدام معلمة داخل سلسلة الاستعلام الملحقة بطلب HTTP، مثل https://adventure-works.com/customers/3?version=2. يجب أن تكون معلمة الإصدار افتراضية إلى قيمة ذات معنى مثل 1 إذا تم حذفها بواسطة تطبيقات العميل الأقدم.

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

إشعار

لن تخزن بعض متصفحات الويب ووكلاء الويب الأقدم استجابات للطلبات التي تتضمن سلسلة استعلام في URI. يمكن أن يؤدي ذلك إلى تدهور أداء تطبيقات الويب التي تستخدم API الويب والتي تعمل من داخل متصفح الويب هذا.

تعيين إصدار العنوان

بدلاً من إلحاق رقم الإصدار كمعلمة سلسلة استعلام، يمكنك تنفيذ عنوان مخصص يشير إلى إصدار المورد. يتطلب هذا الأسلوب أن يضيف تطبيق العميل العنوان المناسب لأي طلبات، على الرغم من أن الكود الذي يتعامل مع طلب العميل يمكن أن يستخدم قيمة افتراضية (الإصدار 1) إذا تم حذف عنوان الإصدار. تستخدم الأمثلة التالية عنواناً مخصصاً يسمى Custom-Header. تشير قيمة هذا العنوان إلى إصدار API الويب.

إصدار 1:

GET https://adventure-works.com/customers/3 HTTP/1.1
Custom-Header: api-version=1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","address":"1 Microsoft Way Redmond WA 98053"}

إصدار 2:

GET https://adventure-works.com/customers/3 HTTP/1.1
Custom-Header: api-version=2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Contoso LLC","dateCreated":"2014-09-04T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

كما هو الحال مع النهجين السابقين، يتطلب تطبيق HATEOAS تضمين العنوان المخصص المناسب في أي روابط.

تعيين إصدار خاص بنوع الوسائط

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

يوضح المثال التالي طلباً يحدد عنوان Accept مع قيمة تطبيق /vnd.adventure-works.v1+json. يشير عنصر vnd.adventure-works.v1 إلى خادم الويب إلى أنه يلزم أن يرجع الإصدار 1 من المورد، بينما يحدد عنصر json أن تنسيق نص الاستجابة يجب أن يكون JSON:

GET https://adventure-works.com/customers/3 HTTP/1.1
Accept: application/vnd.adventure-works.v1+json

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

HTTP/1.1 200 OK
Content-Type: application/vnd.adventure-works.v1+json; charset=utf-8

{"id":3,"name":"Contoso LLC","address":"1 Microsoft Way Redmond WA 98053"}

إذا لم يحدد عنوان قبول أي أنواع وسائط معروفة، يمكن لخادم الويب إنشاء رسالة استجابة HTTP 406 (غير مقبول) أو إعادة رسالة بنوع وسائط افتراضي.

يمكن القول إن هذا النهج هو أنقى آليات الإصدار وهو يفسح المجال بشكل طبيعي لـ HATEOAS، والذي يمكن أن يتضمن نوع MIME من البيانات ذات الصلة في روابط الموارد.

إشعار

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

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

مبادرة API المفتوحة

تم إنشاء مبادرة API المفتوحة من قبل اتحاد صناعي لتوحيد أوصاف API REST عبر الموردين. كجزء من هذه المبادرة، تمت إعادة تسمية مواصفات Swagger 2.0 لتصبح مواصفات OpenAPI (OAS) وتم وضعها ضمن مبادرة Open API.

قد ترغب في اعتماد OpenAPI لواجهات برمجة تطبيقات الويب الخاصة بك. بعض النقاط التي يجب مراعاتها:

تأتي مواصفات OpenAPI مع مجموعة من الإرشادات ذات الرأي حول كيفية تصميم واجهة برمجة تطبيقات REST. هذا له مزايا للتشغيل البيني، لكنه يتطلب مزيدًا من العناية عند تصميم API الخاصة بك لتتوافق مع المواصفات.
يروج OpenAPI لنهج العقد أولاً، بدلاً من نهج التنفيذ أولاً. يعني العقد أولاً أنك تقوم بتصميم عقد API (الواجهة) أولاً ثم كتابة الكود الذي ينفذ العقد.
يمكن لأدوات مثل Swagger إنشاء مكتبات عملاء أو وثائق من عقود API. على سبيل المثال، راجع ASP.NET صفحات تعليمات API الويب باستخدام Swagger.

الخطوات التالية

إرشادات Microsoft Azure REST API. توصيات مفصلة لتصميم واجهات برمجة تطبيقات REST على Azure.
قائمة مراجعة خاصة بـ Web API. قائمة مفيدة بالعناصر التي يلزم مراعاتها عند تصميم API الويب وتنفيذها.
مبادرة API المفتوحة. تفاصيل التوثيق والتنفيذ على Open API.

مشاركة عبر

تصميم API ويب RESTful

ما المقصود بكلمة REST؟

تنظيم تصميم واجهة برمجة التطبيقات فيما يخص الموارد

تحديد عمليات واجهة برمجة التطبيقات من حيث أساليب HTTP

تتفق مع دلالات HTTP

أنواع الوسائط

قسم الأساليب

أساليب خاصة بـ POST

أساليب خاصة بـ PUT

أساليب خاصة بـ PATCH

طرق الحذف

العمليات غير المتزامنة

مجموعات فارغة في أجسام الرسائل

تصفية البيانات وترقيمها

ادعم الاستجابات الجزئية للموارد الثنائية الكبيرة

تعيين إصدار API ويب RESTful

لا يوجد تعيين للإصدار

تعيين إصدار خاص بـ URI

تعيين إصدارات سلسلة الاستعلام

تعيين إصدار العنوان

تعيين إصدار خاص بنوع الوسائط

مبادرة API المفتوحة

الخطوات التالية

الملاحظات

الموارد الإضافية

مشاركة عبر

تصميم API ويب RESTful

ما المقصود بكلمة REST؟

تنظيم تصميم واجهة برمجة التطبيقات فيما يخص الموارد

تحديد عمليات واجهة برمجة التطبيقات من حيث أساليب HTTP

تتفق مع دلالات HTTP

أنواع الوسائط

قسم الأساليب

أساليب خاصة بـ POST

أساليب خاصة بـ PUT

أساليب خاصة بـ PATCH

طرق الحذف

العمليات غير المتزامنة

مجموعات فارغة في أجسام الرسائل

تصفية البيانات وترقيمها

ادعم الاستجابات الجزئية للموارد الثنائية الكبيرة

استخدم HATEOAS لتمكين التنقل إلى الموارد ذات الصلة

تعيين إصدار API ويب RESTful

لا يوجد تعيين للإصدار

تعيين إصدار خاص بـ URI

تعيين إصدارات سلسلة الاستعلام

تعيين إصدار العنوان

تعيين إصدار خاص بنوع الوسائط

مبادرة API المفتوحة

الخطوات التالية

الملاحظات

الموارد الإضافية