106 lines
6.7 KiB
Markdown
106 lines
6.7 KiB
Markdown
---
|
||
title: Rest API Design
|
||
localeTitle: بقية واجهة برمجة التطبيقات تصميم
|
||
---
|
||
### التاريخ
|
||
|
||
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](https://www.youtube.com/watch?v=qCdpTji8nxo)
|
||
|
||
[مناقشة تصميم REST API التي لا تنتهي من قبل غيوم لافورج](https://www.youtube.com/watch?v=48azd2VqtP0)
|
||
|
||
[رموز حالة HTTP](https://httpstatuses.com/) |