فهم واستخدام REST APIs

هناك فرصة كبيرة لأنك صادفت مصطلح "REST API" إذا كنت قد فكرت في الحصول على بيانات من مصدر آخر على الإنترنت ، مثل Twitter أو Github. ولكن ما هي واجهة برمجة تطبيقات REST؟ ماذا يستطيع أن يفعل لك؟ كيف تستخدمه؟

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

ما هي واجهة برمجة تطبيقات REST

لنفترض أنك تحاول العثور على مقاطع فيديو حول Batman على Youtube. تفتح Youtube ، وتكتب Batman في حقل البحث ، وتضغط على Enter ، وستظهر لك قائمة من مقاطع الفيديو حول Batman. تعمل واجهة برمجة تطبيقات REST بطريقة مماثلة. أنت تبحث عن شيء ما ، وتحصل على قائمة بالنتائج من الخدمة التي تطلبها.

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

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

يُطلق على كل عنوان URL طلب بينما يُطلق على البيانات المرسلة إليك استجابة .

تشريح طلب

من المهم أن تعرف أن الطلب يتكون من أربعة أشياء:

1. نقطة النهاية
2. طريقة
3. الرؤوس
4. البيانات (أو الجسم)

نقطة النهاية (أو المسار) هي عنوان url الذي تطلبه. يتبع هذا الهيكل:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

نقطة نهاية الجذر هي نقطة البداية لواجهة برمجة التطبيقات التي تطلب منها. نقطة نهاية الجذر لواجهة برمجة تطبيقات Github هي https://api.github.com بينما تكون واجهة برمجة تطبيقات Twitter الخاصة بنقطة النهاية الجذرية هي https://api.twitter.com .

يحدد المسار المورد الذي تطلبه. فكر في الأمر كجهاز رد آلي يطلب منك الضغط على 1 للحصول على خدمة ، ثم الضغط على 2 لخدمة أخرى ، و 3 لخدمة أخرى وما إلى ذلك.

يمكنك الوصول إلى المسارات تمامًا كما يمكنك الارتباط بأجزاء من موقع الويب. على سبيل المثال ، للحصول على قائمة بجميع المنشورات التي تم وضع علامة عليها ضمن "JavaScript" في مجلة Smashing ، يمكنك الانتقال إلى https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ هو نقطة نهاية الجذر و /tag/javascript هو المسار.

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

 /users/:username/repos

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

نقطة النهاية للحصول على قائمة من المستودعات الخاصة بي على Github هي:

 https://api.github.com/users/zellwk/repos

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

 ?query1=value1&query2=value2

عندما تحاول الحصول على قائمة من مستودعات المستخدم على Github ، فإنك تضيف ثلاث معلمات محتملة إلى طلبك لتعديل النتائج المعطاة لك:

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

 https://api.github.com/users/zellwk/repos?sort=pushed

كيف تعرف ما إذا كانت نقطة النهاية هذه تعمل؟ حسنًا ، حان الوقت لتجربته!

اختبار نقاط النهاية باستخدام curl

يمكنك إرسال طلب بأي لغة برمجة. يمكن لمستخدمي JavaScript استخدام طرق مثل Fetch API وطريقة Ajax في jQuery ؛ يمكن لمستخدمي Ruby استخدام فئة Ruby's Net :: HTTP ، ويمكن لمستخدمي Python استخدام طلبات Python ؛ وما إلى ذلك وهلم جرا.

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

قبل المتابعة ، ستحتاج إلى التأكد من تثبيت cURL على جهازك. افتح Terminal واكتب curl -version . يتحقق هذا الأمر من إصدار cURL الذي قمت بتثبيته على نظامك.

 curl --version

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

لاستخدام cURL ، اكتب curl ، متبوعًا بنقطة النهاية التي تطلبها. على سبيل المثال ، للحصول على نقطة نهاية جذر جيثب ، اكتب ما يلي:

 curl https://api.github.com

بمجرد الضغط على مفتاح الإدخال ، يجب أن تحصل على رد من Github يبدو كالتالي:

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

 curl https://api.github.com/users/zellwk/repos

إذا كنت ترغب في تضمين معامِلات طلب البحث مع cURL ، فتأكد من إضافة شرطة مائلة للخلف ( \ ) قبل علامة ? و = الشخصيات. هذا بسبب ? و = أحرف خاصة في سطر الأوامر. تحتاج إلى استخدام \ قبلهم لسطر الأوامر لتفسيرها كأحرف عادية:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

حاول استخدام أي من الأمرين وتنفيذ طلب! ستحصل على استجابة مماثلة لما رأيته مع Github's root-endpont (ولكن مع الكثير من البيانات).

جسون

JSON (JavaScript Object Notation) تنسيق شائع لإرسال البيانات وطلبها من خلال واجهة برمجة تطبيقات REST. يتم أيضًا تنسيق الرد الذي يرسله Github إليك بتنسيق JSON.

يبدو كائن JSON مثل كائن JavaScript. في JSON ، يجب تغليف كل خاصية وقيمة بعلامات اقتباس مزدوجة ، مثل هذا:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

العودة إلى تشريح طلب

لقد تعلمت أن الطلب يتكون من أربعة أجزاء.

1. نقطة النهاية
2. طريقة
3. الرؤوس
4. البيانات (أو الجسم)

دعنا ننتقل إلى بقية العناصر المكونة للطلب.

طريقة

الطريقة هي نوع الطلب الذي ترسله إلى الخادم. يمكنك الاختيار من بين هذه الأنواع الخمسة أدناه:

• GET
• POST
• PUT
• PATCH
• DELETE

توفر هذه الأساليب معنى للطلب الذي تقدمه. يتم استخدامها لأداء أربعة إجراءات ممكنة: Read Create Update Delete (CRUD).

تتيح لك واجهة برمجة التطبيقات معرفة طريقة الطلب لاستخدام كل طلب. على سبيل المثال ، للحصول على قائمة من مستودعات المستخدم ، تحتاج إلى طلب GET :

مطلوب طلب GET للحصول على قائمة المستودعات من المستخدم. لإنشاء مستودع Github جديد ، تحتاج إلى طلب POST :

يمكنك ضبط طريقة الطلب في cURL عن طريق كتابة -X أو --request ، متبوعة بطريقة الطلب. يحاول هذا الأمر أدناه إنشاء مستودع عبر cURL:

 curl -X POST https://api.github.com/user/repos

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

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

الرؤوس

تستخدم الرؤوس لتوفير المعلومات لكل من العميل والخادم. يمكن استخدامه لأغراض عديدة ، مثل المصادقة وتقديم معلومات حول محتوى الجسم. يمكنك العثور على قائمة بالرؤوس الصالحة في مرجع رؤوس HTTP الخاص بـ MDN.

رؤوس HTTP هي أزواج خاصية-قيمة مفصولة بنقطتين. يوضح المثال أدناه رأسًا يخبر الخادم أن يتوقع محتوى JSON.

 "Content-Type: application/json". Missing the opening ".

يمكنك إرسال رؤوس HTTP مع curl من خلال الخيار -H أو --header . لإرسال الرأس أعلاه إلى واجهة برمجة تطبيقات Github ، يمكنك استخدام هذا الأمر:

 curl -H "Content-Type: application/json" https://api.github.com

(ملاحظة: رأس نوع المحتوى ليس شرطًا لواجهة برمجة تطبيقات Github للعمل. هذا مجرد مثال لتوضيح كيفية استخدام رأس مع cURL).

لعرض الرؤوس التي أرسلتها ، يمكنك استخدام الخيار -v أو --verbose أثناء إرسال الطلب ، على النحو التالي:

 curl -H "Content-Type: application/json" https://api.github.com -v 

هنا ، تشير * إلى المعلومات الإضافية التي يوفرها cURL. > يشير إلى رؤوس الطلبات ، ويشير < إلى رؤوس الاستجابة.

البيانات (أو "الجسم")

البيانات (تسمى أحيانًا "نص" أو "رسالة") تحتوي على معلومات تريد إرسالها إلى الخادم. يستخدم هذا الخيار فقط مع طلبات POST أو PUT أو PATCH أو DELETE .

لإرسال البيانات من خلال cURL ، يمكنك استخدام الخيار -d أو --data :

 curl -X POST <URL> -d property1=value1

لإرسال حقول بيانات متعددة ، يمكنك إنشاء خيارات متعددة -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

إذا كان ذلك منطقيًا ، يمكنك تقسيم طلبك إلى عدة أسطر \ لتسهيل قراءته:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

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

إذا كنت لا ترغب في تدوير الخادم الخاص بك ، فيمكنك الانتقال إلى Requestbin.com ( مجاني! ) والنقر فوق "إنشاء نقطة نهاية". ستحصل على عنوان URL يمكنك استخدامه لاختبار الطلبات ، مثل https://requestb.in/1ix963n1 الموضح في الصورة أدناه.

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

الآن ، حاول إرسال بعض البيانات إلى سلة الطلبات الخاصة بك ، ثم قم بتحديث صفحة الويب الخاصة بسلة المهملات. سترى بعض البيانات ، مثل هذا:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

بشكل افتراضي ، يرسل cURL البيانات كما لو تم إرسالها من خلال "حقول النموذج" على الصفحة. إذا كنت ترغب في إرسال بيانات JSON ، فستحتاج إلى تعيين Content-Type على application/json ، وستحتاج إلى تنسيق بياناتك ككائن JSON ، مثل هذا:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

وهذا (تقريبًا!) كل ما تحتاج لمعرفته حول بنية الطلب.

الآن ، تذكر عندما حاولت إرسال طلب POST من خلال Github's API ، تلقيت رسالة تقول "يتطلب المصادقة"؟ حسنًا ، هذا لأنك غير مصرح لك بتنفيذ طلب POST !

المصادقة

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

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

على الويب ، هناك طريقتان رئيسيتان لمصادقة نفسك:

1. باستخدام اسم مستخدم وكلمة مرور (تسمى أيضًا المصادقة الأساسية)
2. مع رمز سري

تشتمل طريقة الرمز السري على oAuth ، والتي تتيح لك المصادقة على شبكات التواصل الاجتماعي مثل Github و Google و Twitter و Facebook وما إلى ذلك.

في هذه المقالة ، ستتعلم فقط استخدام المصادقة الأساسية باستخدام اسم مستخدم وكلمة مرور. إذا كنت مهتمًا بالمصادقة باستخدام oAuth ، أقترح قراءة "ما تحتاج لمعرفته حول OAuth2 وتسجيل الدخول باستخدام Facebook" بقلم Zack Grossbart.

لإجراء مصادقة أساسية باستخدام cURL ، يمكنك استخدام الخيار -u ، متبوعًا باسم المستخدم وكلمة المرور ، على النحو التالي:

 curl -x POST -u "username:password" https://api.github.com/user/repos

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

هذا لأنك لم تقدم بعد أي بيانات (وهي مطلوبة من قبل جميع طلبات POST و PUT و PATCH و DELETE ) إلى الخادم.

من خلال المعرفة التي تعلمتها حتى الآن ، يجب أن تكون قادرًا على تحرير الكود أعلاه لإنشاء مستودع Github عبر cURL. سأتركك لتجربتها بنفسك!

الآن ، دعنا نتحدث عن رموز حالة HTTP ورسائل الخطأ.

رموز حالة HTTP ورسائل الخطأ

بعض الرسائل التي تلقيتها سابقًا ، مثل "يتطلب المصادقة" و "مشكلات تحليل JSON" هي رسائل خطأ. تظهر فقط عندما يكون هناك خطأ ما في طلبك. تتيح لك أكواد حالة HTTP معرفة حالة الاستجابة بسرعة. النطاق من 100+ إلى 500+. بشكل عام ، تتبع الأرقام القواعد التالية:

1. 200+ يعني أن الطلب قد نجح .
2. 300+ يعني إعادة توجيه الطلب إلى عنوان URL آخر
3. 400+ يعني حدوث خطأ ناشئ من العميل
4. +500 يعني حدوث خطأ نشأ من الخادم

يمكنك تصحيح حالة الاستجابة باستخدام الخيار المطول ( -v أو - --verbose ) أو خيار الرأس ( -I أو --head ).

على سبيل المثال ، إذا حاولت إضافة -I إلى طلب POST دون تقديم اسم المستخدم وكلمة المرور ، فستحصل على رمز الحالة 401 (غير مصرح به):

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

للحصول على مزيد من المعلومات حول رموز حالة HTTP المحددة ، قد ترغب في استشارة مرجع حالة HTTP الخاص بـ MDN.

إصدارات API

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

يمكنك طلب إصدار محدد من واجهة برمجة التطبيقات بطريقتين. تعتمد الطريقة التي تختارها على كيفية كتابة API.

هاتان الطريقتان هما:

1. مباشرة في نقطة النهاية
2. في عنوان الطلب

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

 https://api.twitter.com/1.1/account/settings.json

من ناحية أخرى ، يستخدم Github الطريقة الثانية. في وقت كتابة هذا التقرير ، كانت واجهة برمجة تطبيقات Github في الإصدار 3 ، ويمكنك تحديد الإصدار برأس Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

تغليف

في هذه المقالة ، تعلمت ماهية واجهة برمجة تطبيقات REST وكيفية استخدام cURL لتنفيذ طلب باستخدام طرق GET و POST و PUT و PATCH و DELETE . بالإضافة إلى ذلك ، تعلمت أيضًا كيفية مصادقة طلباتك باستخدام الخيار -u وما تعنيه حالات HTTP.

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