freeCodeCamp/guide/arabic/rest-api/index.md

title	localeTitle
Rest API Design	بقية واجهة برمجة التطبيقات تصميم

التاريخ

REST لتقف على إعادة تقديم S tate T ransfer protocol. حدد روي فيلدنغ REST في أطروحته لنيل درجة الدكتوراه عام 2000.

ما هذا؟

تم تطوير REST لتوفير واجهة موحدة لـ

• تحديد الموارد
• التلاعب في الموارد
• رسائل وصفية ذاتية
• استخدام Hypermedia كمحرك لدولة التطبيق (HATEOS)

أفضل الممارسات

• #### أساسيات

| الطريقة | http://api.co/v2/cars | http://api.co/v2/cars/1234 |
| --- | --- | --- | | الحصول على | قائمة جميع السيارات | استرجاع سيارة فردية | POST | إنشاء سيارة جديدة | خطأ | | ضع | استبدال مجموعات السيارات بأخرى جديدة | استبدل السيارة بالمعرف 1234 | | حذف حذف جميع السيارات | حذف سيارة بمعرف 1234 |

ملاحظة أثناء عمليات PUT إما العميل أو الخادم يمكن إنشاء معرف

• الأسماء هي أفعال جيدة سيئة

• استخدم الأسماء للإشارة إلى الموارد مثل cars fruits وما إلى ذلك.

• استخدام الأفعال لإعلانات العمل convertMilesToKms ، getNutritionalValues

• مفرد أم جمع؟

  استخدم القواعد الصحيحة للإعلان

  تجنب /person/145

  تفضل /people/154 افترض أن تعود 154 شخصًا من قائمة الأشخاص

• استخدم الغلاف

  استخدام أي شخص من الأنماط أدناه وتكون متسقة!

  | أنماط القضية مثال | | ------------- | ------------- | | UpperCamelCase | http://api.fintech.cp/DailyTransactions/Today | | lowerCamelCase | http://api.fintech.cp/dailyTransactions/today |
  | snake_case | http://api.fintech.cp/daily_transactions/today |

• العلاقات والموارد

• يمكن لموارد يكون one-to-many ، many-to-many ، many-to-one علاقات الخ رسم خريطة بشكل صحيح أمر بالغ الأهمية.

• واحد إلى العديد من الخرائط

  على سبيل المثال ، تشير Tickets/145/messages/4 إلى علاقة رأس بأطراف بين tickets messages . معنى 1 تذكرة لديها رسائل N الرسالة ليست موردًا مستقلًا. لا يمكن أن يكون لديك /messages/4 .

• العديد من العديد من الخرائط

  على سبيل المثال ، /usergroups/345/users/56 يقترح اختيار مجموعة المستخدم 345th والحصول على المستخدم مع معرف 56. ومع ذلك ، قد يكون مستخدم واحد في usergroups متعددة أي /usergroups/209/users/56 صالح أيضا. في مثل هذه الحالة ، وذلك لفصل users الموارد المخولين إلى نقطة نهائية منفصلة مثل /users/56 وتوفير ارتباط الموارد في /usergroups/209/users/56

• معلمات واجهة برمجة التطبيقات

• PATH : مطلوب للوصول إلى المورد Eg /cars ، /fruits

• معلمات الاستعلام : فلتر اختياري القائمة Eg /cars?type=SUV&year=2010

• Body : منطق محدد للموارد. طلب بحث متقدم. في بعض الأحيان قد يكون له كل من الاستعلام والجسد.

• العنوان : يجب أن يحتوي على بيانات عالمية أو على مستوى النظام الأساسي. على سبيل المثال ، معلمات مفتاح API ، ومفاتيح مشفرة للمصادقة ، ومعلومات نوع الجهاز ، مثل الجوال أو سطح المكتب أو نقطة النهاية ، نوع بيانات الجهاز مثل xml أو json. استخدم رأس لتوصيل هذه المعلمات

• رموز حالة HTTP

  استخدم رموز الحالة الصحيحة

  | الرموز المعنى | | ------------- |: -------------: | | 1xx | تلقي الطلب وفهمه. | | 2xx | تم استلام الإجراء المطلوب من قبل العميل وفهمه وطلبه. | | 3xx | يجب على العميل اتخاذ إجراء إضافي لإكمال الطلب. يتم استخدام معظم رموز الحالة هذه في إعادة توجيه عنوان URL. | | 4xx | مخصص للحالات التي يبدو فيها أن الخطأ كان بسبب العميل. | | 5xx | فشل الخادم في تلبية الطلب. |

  أكثر قليلا على 2xx !

• 201 مورد تم إنشاؤه. يجب أن تقوم POST /cars بإرجاع HTTP 201 الذي تم إنشاؤه باستخدام رأس location يوضح كيفية الوصول إلى المورد على سبيل المثال ، location : api.com/cars/124 في رأس الصفحة

• 202 - مقبول

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

• 204 - لا محتوى

  تستخدم عند حذف DELETE cars/124 لا يعرض أي محتوى. ولكن يمكن أيضًا إرجاع 200 OK إذا كانت واجهة برمجة التطبيقات تعتزم إرسال المورد المحذوف لمزيد من المعالجة.

  موارد 5xx خطيرة!

• 500 خطأ خادم داخلي

• 504 عبّارة المهلة. الخادم لم يتلق استجابة في الوقت المناسب

  تشير 4xx أقل شهرة إلى أنك تمر بمعلمة خاطئة. يمكن أيضا تمرير المعلومات التي هي خاطئة. على سبيل المثال

  DELETE /cars/MH09234

  إرجاع 4xx أو رسالة Expecting int car id /car/id got string car/MH09234

قراءة متعمقة

كيفية تصميم واجهات برمجة التطبيقات (APIs) الرائعة - يوم تطوير المطور 2013

مناقشة تصميم REST API التي لا تنتهي من قبل غيوم لافورج

رموز حالة HTTP