دليل شامل لـ Fetch API: تسعة من أكثر طلبات الـ API شيوعًا

في عالم تطوير الويب الحديث، أصبح التفاعل مع العالم الخارجي ضرورة قصوى لكل مشروع تقريبًا. إذا كنت تعمل ضمن بيئة إطارات عمل JavaScript، فمن المرجح أنك تعتمد بشكل كبير على واجهة Fetch API لإنجاز هذه المهمة. ولكن، هل تتذكر دائمًا البنية الدقيقة لكل طلب من طلبات الـ API عن ظهر قلب، أم أنك تحتاج أحيانًا إلى مرجع سريع؟
لقد قمت بكتابة العديد من المقالات حول JavaScript وما يتعلق بها، ووجدت نفسي لاحقًا أعود إليها مرارًا لتحديث ذاكرتي أو للحصول على نموذج كود معين أعلم أنه “موجود هناك”. في هذا المقال، أهدف إلى إنشاء مصدر مشابه، حيث سأستعرض لك تسعة من أكثر طلبات Fetch API شيوعًا. أنا متأكد أنك استخدمتها جميعًا مرات عديدة، ولكن ألن يكون من الرائع تجنب البحث في المشاريع القديمة للعثور على بنية طلب معين استخدمته قبل ستة أشهر؟ هذا الدليل سيقدم لك الخلاصة.

لماذا نستخدم Fetch API؟

في عصرنا الحالي، أصبحت العديد من الخدمات توفر حزم تطوير برمجيات (SDKs) ممتازة، والتي تُجرّد تفاصيل طلبات واجهة برمجة التطبيقات (API) الفعلية. نحن ببساطة نطلب البيانات باستخدام بناءات لغوية مألوفة، ولا نضطر للقلق بشأن عملية تبادل البيانات الفعلية. ولكن ماذا لو لم يتوفر SDK للمنصة التي اخترتها؟ أو ماذا لو كنت تقوم ببناء كل من الخادم والعميل بنفسك؟ في هذه الحالات، ستحتاج إلى التعامل مع الطلبات يدويًا. وهنا يأتي دور Fetch API كحل فعال وقوي لإدارة هذه التفاعلات.

طلب GET بسيط باستخدام Fetch API

يُعد طلب GET هو الأساس لاسترداد البيانات من خادم. إليك كيفية تنفيذه بأبسط صورة باستخدام Fetch API:

fetch( '{url}' )
.then( response => console .log(response));

طلب POST بسيط باستخدام Fetch API

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

fetch( '{url}' , {
    method : 'post'
})
.then( response => console .log(response));

طلب GET مع رمز مصادقة (Bearer Token)

تتطلب العديد من واجهات الـ API المصادقة للوصول إلى الموارد المحمية. يمكن تمرير رمز المصادقة (Authorization Token) ضمن ترويسات الطلب (headers) كما يلي:

fetch( '{url}' , {
    headers : {
        'Authorization' : 'Bearer {token}'
    }
})
.then( response => console .log(response));

طلب GET مع بيانات في سلسلة الاستعلام (Querystring)

يمكن تمرير المعلمات الإضافية لطلبات GET مباشرة ضمن عنوان URL كجزء من سلسلة الاستعلام (querystring). هذا شائع لتصفية البيانات أو تحديدها:

fetch( '{url}?var1=value1&var2=value2' )
.then( response => console .log(response));

طلب GET مع دعم CORS

عند التعامل مع طلبات عبر النطاقات (Cross-Origin Requests)، قد تحتاج إلى تحديد وضع CORS لضمان السماح بالطلب من متصفحك. هذا يتيح لك التفاعل مع واجهات API الموجودة على نطاقات مختلفة:

fetch( '{url}' , {
    mode : 'cors'
})
.then( response => console .log(response));

طلب POST مع رمز مصادقة وبيانات سلسلة الاستعلام

في بعض السيناريوهات، قد تحتاج إلى دمج طلب POST مع رمز مصادقة وتمرير بعض البيانات عبر سلسلة الاستعلام في نفس الوقت:

fetch( '{url}?var1=value1&var2=value2' , {
    method : 'post' ,
    headers : {
        'Authorization' : 'Bearer {token}'
    }
})
.then( response => console .log(response));

طلب POST مع بيانات النموذج (Form Data)

لإرسال بيانات نموذج (form data) إلى الخادم، كما هو الحال عند تحميل ملف أو إرسال بيانات نموذج HTML، يمكنك استخدام كائن FormData:

 let formData = new FormData();
formData.append( 'field1' , 'value1' );
formData.append( 'field2' , 'value2' );

fetch( '{url}' , {
    method : 'post' ,
    body : formData
})
.then( response => console .log(response));

طلب POST مع بيانات JSON

تعد بيانات JSON التنسيق الأكثر شيوعًا لتبادل البيانات مع واجهات الـ API الحديثة. لإرسال بيانات JSON، يجب تحديد ترويسة Content-Type وتمرير البيانات ككائن JSON محوّل إلى نص باستخدام JSON.stringify():

fetch( '{url}' , {
    method : 'post' ,
    headers : {
        'Content-Type' : 'application/json'
    },
    body : JSON .stringify({
        'field1' : 'value1' ,
        'field2' : 'value2'
    })
})
.then( response => console .log(response));

طلب POST مع بيانات JSON ودعم CORS

عند إرسال بيانات JSON إلى خادم على نطاق مختلف، من الضروري دمج وضع CORS مع تحديد نوع المحتوى لضمان نجاح الطلب:

fetch( '{url}' , {
    method : 'post' ,
    mode : 'cors' ,
    headers : {
        'Content-Type' : 'application/json'
    },
    body : JSON .stringify({
        'field1' : 'value1' ,
        'field2' : 'value2'
    })
})
.then( response => console .log(response));

كيفية معالجة نتائج طلب Fetch API

تعيد Fetch API كائن Promise. لهذا السبب، غالبًا ما نستخدم الدالة .then() ودالة رد الاتصال (callback function) لمعالجة الاستجابة:

fetch(...).then( response => {
    // process the response
});

ولكن يمكنك أيضًا استخدام await للحصول على النتيجة مباشرة إذا كنت داخل دالة غير متزامنة (async function):

 async function getData ( ) {
    let data = await fetch(...);
    // process the response
}

الآن، دعنا نلقي نظرة على كيفية استخراج البيانات من الاستجابة.

كيفية التحقق من رمز حالة استجابة Fetch API

عند إرسال طلبات POST أو PATCH أو PUT، غالبًا ما نكون مهتمين برمز حالة الاستجابة (status code) للتحقق من نجاح العملية أو فشلها:

fetch(...)
.then( response => {
    if (response.status == 200 ){
        // all OK
    } else {
        console .log(response.statusText);
    }
});

كيفية الحصول على قيمة بسيطة من استجابة Fetch API

قد تعيد بعض نقاط نهاية الـ API قيمة بسيطة، مثل معرف (identifier) لسجل قاعدة بيانات جديد تم إنشاؤه. يمكن استخراج هذه القيمة باستخدام .text():

 var userId;
fetch(...)
.then( response => response.text())
.then( id => {
    userId = id;
    console .log(userId)
});

كيفية تحويل بيانات JSON من استجابة Fetch API

في معظم الحالات، ستتلقى بيانات بتنسيق JSON في جسم الاستجابة (response body). لتحويلها إلى كائن JavaScript، يمكنك استخدام .json():

 var dataObj;
fetch(...)
.then( response => response.json())
.then( data => {
    dataObj = data;
    console .log(dataObj)
});

تذكر أنه لا يمكنك الوصول إلى البيانات إلا بعد أن يتم حل كلا الـ Promises. قد يكون هذا مربكًا بعض الشيء أحيانًا، لذا أفضل دائمًا استخدام الدوال غير المتزامنة (async methods) و await النتائج لتبسيط العملية:

 async function getData ( ) {
    var dataObj;
    const response = await fetch(...);
    const data = await response.json();
    dataObj = data;
    console .log(dataObj);
}

الخلاصة التقنية

لقد استعرضنا في هذا الدليل تسعة من أكثر طلبات Fetch API شيوعًا، والتي تغطي معظم السيناريوهات التي قد تواجهها في مشاريع تطوير الويب. من الطلبات البسيطة لاسترداد البيانات إلى إرسال بيانات JSON المعقدة مع المصادقة ودعم CORS، يمثل Fetch API أداة قوية ومرنة للتفاعل مع واجهات برمجة التطبيقات.
إن فهم هذه الأساسيات سيساعدك على بناء تطبيقات ويب أكثر كفاءة واستجابة. تذكر دائمًا أهمية التعامل مع الـ Promises أو استخدام async/await لمعالجة الاستجابات بشكل صحيح وضمان تجربة مستخدم سلسة.