6.7 KiB
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