ضع رمز API الأول الخاص بك مع Node.js و Express: فهم واجهات برمجة تطبيقات REST

فهم ريست و تطبيقات ريست فل

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

 في هذه السلسلة التعليمية ، سنبدأ بنظرة عامة على مبادئ REST ومفاهيمها. ثم سنستمر لإنشاء واجهة برمجة التطبيقات الخاصة بنا بالكامل والتي تعمل على خادم Node.js Express وتتصل بقاعدة بيانات MySQL.  بعد الانتهاء من هذه السلسلة ، يجب أن تشعر بالثقة لبناء واجهة برمجة التطبيقات الخاصة بك أو الخوض في توثيق واجهة برمجة تطبيقات حالية.

المتطلبات الأساسية

 للحصول على أقصى استفادة من هذا البرنامج التعليمي ، يجب أن يكون لديك بالفعل بعض المعرفة الأساسية في سطر الأوامر ، وأن تعرف أساسيات JavaScript ، وأن تقوم بتثبيت Node.js على مستوى العالم.

• 
  نصائح و ادوات 
  سطر الأوامر الخاص بك هو أفضل صديق
  باتكوس Csaba 

ما هي ريست و تطبيقات ريست فل؟

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

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

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

 مبادئ ريست

ستة قيود توجيهية تقم بتعريف بنية ريست، المبينة أدناه.

1. واجهة موحدة: يجب أن تكون واجهة المكونات هي نفسها. وهذا يعني استخدام معيار URI لتحديد الموارد - وبعبارة أخرى ، المسارات التي يمكن إدخالها في شريط موقع المتصفح. 
2. خادم العميل: هناك فصل بين المخاوف بين الخادم الذي يخزن البيانات ويقوم بمعالجتها والعميل الذي يطلب الاستجابة ويعرضها
3. تفاعلات بدون الحالة: كل المعلومات المتعلقة بكل طلب واردة في كل طلب فردي ولا تعتمد على حالة الجلسة 
4. قابلة للتخزين المؤقت: العميل والخادم يمكنهم تخزين موارد.
5.  نظام الطبقات: يمكن توصيل العميل بالخادم النهائي ، أو طبقة وسيطة مثل موازن التحميل.
6. الشفرة عند الطلب (اختياري):يمكن للعميل تنزيل الرمز ، مما يقلل من الرؤية من الخارج. 

الطلب والاستجابة

 ستعرف بالفعل أن جميع مواقع الويب لها عناوين URL تبدأ بـ http (أو https للإصدار الآمن). بروتوكول نقل النص التشعبي ، أو HTTP ، هي طريقة التواصل بين العملاء والخوادم على الإنترنت.

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

 يعمل HTTP عن طريق فتح اتصال TCP (بروتوكول التحكم بالإرسال) بمنفذ الخادم (80 لـ http ، 443 لـ https) لتقديم طلب ، ويستجيب خادم الاستماع مع حالة وجسم.

يجب أن يحتوي الطلب URL وأسلوب ومعلومات الرأس وهيئة.

أساليب الطلب

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

 تتوافق طرق طلب HTTP بشكل حر مع نموذج CRUD ، الذي يرمز لـ Create أو Update أو Read أو Delete. على الرغم من أن CRUD يشير إلى الوظائف المستخدمة في عمليات قاعدة البيانات ، يمكننا تطبيق مبادئ التصميم هذه على أفعال HTTP في RESTful API. 

GET هي على عملية آمنة أو للقراءة فقط لأنه لن يغير من حالة الخادم. في كل مرة تضغط على عنوان URL في المستعرض الخاص بك، مثل https://www.google.com، يتم إرسال طلب GET إلى خوادم Google.

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

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

حذف، كما يوحي اسمها، سيؤدي ببساطة حذف مورد موجود.

رموز استجابة

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

رمز الاستجابة الأكثر شيوعًا الذي ستعرفه هو 404 ، مما يعني أنه غير موجود. 404 جزءًا من فئة 4xx من رموز الحالة ، والتي تشير إلى أخطاء العميل. هناك خمس فئات من رموز الحالة تحتوي كل منها على مجموعة من الاستجابات. 

• 1xx: المعلومات
• 2xx: نجاح
  
• 3xx: إعادة توجيه
  
• 4xx: خطأ العميل
  
• 5xx: خطأ في الخادم

الاستجابات الشائعة الأخرى التي قد تكون معتادًا عليها هي 301 Moved Permanently ، والتي تُستخدم لإعادة توجيه مواقع الويب إلى عناوين URL الجديدة ، و 500 خطأ داخلي في الخادم ، وهو خطأ يحدث كثيرًا عندما يحدث أمر غير متوقع على خادم يجعل من المستحيل تلبية الطلب المقصود.

فيما يتعلق "واجهات برمجة التطبيقات مريح" وHTTP المقابلة لهم، ينبغي أن تكون جميع الردود في نطاق 2xx.

200 OK هي الاستجابة التي تشير إلى نجاح الطلب. يتم استخدامه كرد عند إرسال طلب GET أو PUT. سيعيد بوست 201 تم إنشاؤه للإشارة إلى أنه قد تم إنشاء مورد جديد ، ولدى DELETE بعض الاستجابات المقبولة ، والتي تنقل إما أن الطلب قد تم قبوله (202) ، أو لا يوجد محتوى لإرجاعه لأن المورد لم يعد موجودًا (204).

يمكننا اختبار رمز حالة من طلب المورد باستخدام حليقة، الذي أداة سطر أوامر المستخدمة لنقل البيانات عبر عناوين Url. سيؤدي استخدام curl ، متبوعًا بعلامة -i أو - include ، إلى إرسال طلب GET إلى عنوان URL وعرض العناوين والجسم. يمكننا اختبار ذلك من خلال فتح برنامج سطر الأوامر واختبار cURL باستخدام Google. 

1

curl -i https://www.google.com

وسوف يستجيب الملقم Google بما يلي.

1

HTTP/2 200 

2

date: Tue, 14 Aug 2018 05:15:40 GMT 

3

expires: -1 

4

cache-control: private, max-age=0 

5

content-type: text/html; charset=ISO-8859-1 

6

...

 كما يمكننا أن نرى ، يقوم طلب curl بإرجاع عناوين متعددة وجسم HTML بأكمله للاستجابة. نظرًا لأن الطلب تم بنجاح ، فإن الجزء الأول من الاستجابة هو 200 رمز حالة ،معا بالإضافة إلى إصدار HTTP (سيكون إما HTTP / 1.1 أو HTTP / 2).

نظرًا لأن هذا الطلب المحدد يعرض موقعًا إلكترونيًا ، فإن نوع المحتوى (نوع MIME) الذي يتم إرجاعه هو text / html. في واجهة برمجة تطبيق RESTful ، من المرجح أن ترى التطبيق / json للإشارة إلى أن الإجابة هي JSON.

من المثير للاهتمام، يمكن أن نرى نوع آخر من الاستجابة عن طريق إدخال عنوان URL مختلفاً بعض الشيء. قم ب curl  في جوجل دون www.

1

curl -i https://google.com

1

HTTP/2 301 

2

location: https://www.google.com/ 

3

content-type: text/html; 

4

charset=UTF-8

تعيد Google توجيه google.com إلى www.google.com ، وتستخدم استجابة 301 للإشارة إلى أنه يجب إعادة توجيه المورد.

النقاط النهائية لتطبيق ريست

عندما يتم إنشاء واجهة برمجة التطبيقات على خادم ، فإن البيانات التي تحتويها يمكن الوصول إليها عبر نقاط النهاية. نقطة النهاية هي عنوان URL للطلب الذي يمكنه قبول طلب GET أو POST أو PUT أو DELETE ومعالجته.

سيتكون عنوان URL الخاص بـ API من الجذر ، والمسار ، وسلسلة الاستعلام الاختيارية

• الجذر على سبيل المثال https://api.example.com أو https://api.example.com/v2: جذر واجهة برمجة التطبيق ، التي قد تتكون من البروتوكول والمجال والإصدار.
• مسار على سبيل المثال / users / or / users / 5: موقع فريد لمورد معين.
• معلمات الاستعلام (اختياري) على سبيل المثال ؟ location = chicago & age = 29: أزواج القيم الأساسية الاختيارية المستخدمة في الفرز والتصفية وترقيم الصفحات.
  يمكننا أن نجمعهم جميعًا لتنفيذ شيء ما مثل المثال أدناه ، والذي سيؤدي إلى عرض قائمة بجميع المستخدمين واستخدام متغير بحث ذا حد لتصفية الردود بحيث تتضمن فقط عشر نتائج.

https://api.example.com/users?limit=10

بشكل عام ، عندما يشير الأشخاص إلى واجهة برمجة التطبيقات (API) باعتبارها واجهة برمجة تطبيقات (REST) ​​، فإنهم يشيرون إلى اصطلاحات التسمية التي تدخل في نقاط نهاية عنوان URL لواجهة برمجة التطبيق. فيما يلي بعض الاتفاقيات الهامة الخاصة بـ RESTful API:

• يجب أن تكون المسارات متعددة: على سبيل المثال ، للحصول على المستخدم بمعرف 5 ، سنستخدم / users / 5 ، وليس / user / 5.
• لا يجب أن تعرض نقاط النهاية امتداد الملف: على الرغم من أن واجهة برمجة التطبيق على الأرجح ستعرض JSON ، فإن عنوان URL يجب ألا ينتهي بـ .json.
• يجب أن تستخدم نقاط النهاية الأسماء وليس الأفعال: يجب ألا تظهر الكلمات مثل اضافة والحذف في عنوان URL لـ REST. من أجل إضافة مستخدم جديد ، يمكنك ببساطة إرسال طلب POST إلى / المستخدمين ، وليس شيء مثل / المستخدمين / إضافة. يجب تطوير واجهة برمجة التطبيقات للتعامل مع أنواع متعددة من الطلبات على عنوان URL نفسه.
• تكون المسارات حساسة لحالة الأحرف ، ويجب أن تكون مكتوبة بأحرف صغيرة مع واصلات مقارنة بالشُرط السفلية

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

الاستنتاج

 في هذه المقالة ، تعلمنا ما هي واجهات برمجة تطبيقات REST و RESTful ، وكيفية عمل رموز طلب HTTP وبروتوكولات الاستجابة ، وهيكل عنوان URL API ، واتفاقيات RESTful API الشائعة. في البرنامج التعليمي التالي ، سوف نتعلم كيفية وضع كل هذه النظرية لاستخدامها من خلال إعداد خادم Express مع Node.js وبناء API الخاص بنا.