چگونه در جاوا اسکریپت یک API را فراخوانی کنیم؟

فراخوانی یا Call کردن API در جاوا اسکریپت یکی از مهمترین و پایه‌ای‌ترین کارهایی‌ست که هر توسعه دهنده وبی باید شیوه انجام آن را بداند. با استفاده از این تکنیک می‌توانید از طریق منابع خارج از وبسایت، داده دریافت کنید و آن را با وب اپلیکیشن خودتان ادغام کنید.

در این مطلب از وبسایت راکت ما به صورت پایه‌ای شما را با فراخوانی API در جاوا اسکریپت آشنا می‌کنیم و همچنین تعاریف اصلی در این فرایند را یاد خواهیم گرفت.

API چیست؟

قبل از اینکه وارد جزئیات تکنیکی مربوط به فراخوانی API در جاوا اسکریپت برویم نیاز است که با یکسری از تعاریف پایه‌ای آشنا شوید. API در واقع یک رابط برنامه نویسی میان دو اپلیکیشن است که امکان انتقال داده بین دو اپلیکیشن را فراهم می‌کند.

در فرایند کار با API شما می‌توانید داده‌های جدیدی را از یک منبع خارجی دریافت کنید و یا اینکه به یک سرویس خارجی یکسری اطلاعات ارسال کنید. البته این تنها ابتدایی‌ترین کارهایی‌ست که با استفاده از API انجام می‌شود. از API در دنیای وب به صورت گسترده استفاده می‌شود و تقریبا هیچ اپلیکیشنی وجود ندارد که از یک سرویس مبتنی بر API استفاده نکند.

فراخوانی API با استفاده از درخواست GET

برای اینکه یک درخواست API در جاوا اسکریپت ایجاد کنید می‌توانید از ابزار fetch استفاده کنید که در مرورگرهای جدید به صورت کامل پشتیبانی می‌شود. با استفاده از fetch که در واقع خود یک API است می‌توانید درخواست‌های HTTP را ارسال کنید و همزمان پاسخ‌ها را مدیریت کنید.

در زیر می‌توانید یک نمونه از شیوه فراخوانی API با استفاده از ابزار Fetch را مشاهده کنید:

// Define the API URL
const apiUrl = 'https://api.example.com/data';

// Make a GET request
fetch(apiUrl)
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

توضیح کد بالا به صورت مرحله به مرحله:

• ابتدا URL درخواستی که می‌خواهیم API Request از آن داده دریافت کند را تعیین می‌کنیم.
• بعد از تعیین آدرس درخواستی، با استفاده از تابع fetch درخواست GET مورد نظر را ایجاد می‌کنیم. بعد از اینکار تابع fetch یک Promise را برمی‌گرداند.
• متد .then وظیفه ایجاد پاسخ همزمان از سرور را برعهده دارد. (asynchronous response)
• پراپرتی response.ok در مرحله بعد از معتبر بودن پاسخ دریافتی مطمئن می‌شود.
• در مرحله بعد با استفاده از متد response.json() اطلاعات JSON دریافتی را تفسیر یا parse می‌کنیم.
• در نهایت ما با استفاده از console.log() خروجی مورد نظر را به نمایش می‌گذاریم.

چگونه پاسخ‌ها یا Responseها را مدیریت کنیم؟

زمانی که فرایند فراخوانی API را دنبال می‌کنید، سرور مقصد پس از ارتباط‌گیری درست، به درخواست شما جواب می‌دهد. این جواب با ارسال داده همراه است. حال که شما جواب مورد نظر را دریافت کرده‌اید نیاز است که شیوه مدیریت آن پاسخ‌ها را یاد بگیرید.

در مثال قبلی ما تنها داده‌های دریافتی را از طریق console.log نمایش دادیم. اما شما می‌توانید داده‌های دریافتی را به روش‌های مختلفی پردازش کنید.  برای مثال می‌توانید داده‌های دریافتی را در وبسایت خود نشان دهید و یا آن را در دیتابیس‌تان ذخیره کنید.

در زیر یک روش دیگر برای نمایش API Response را می‌توانید مشاهده کنید:

const apiUrl = 'https://api.example.com/data';
const outputElement = document.getElementById('output');

fetch(apiUrl)
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => {
    // Display data in an HTML element
    outputElement.textContent = JSON.stringify(data, null, 2);
  })
  .catch(error => {
    console.error('Error:', error);
  });

در مثال بالا ما از متغیر outputElement برای انتخاب یک عنصر HTML استفاده کرده‌ایم. این عنصر مسئول نمایش داده‌ها را برعهده خواهد داشت. خاصیت textContent در کدهای بالا نیز برای بروزرسانی محتوای داده‌های JSON استفاده می‌شود.

مدیریت خطا در فراخوانی API

مدیریت خطا یا Error Handling بخش بسیار مهمی از فرایند API Calling در جاوا اسکریپت است. درخواست‌های API می‌توانند بنابر دلایل مختلفی با شکست روبرو شوند و در نتیجه نیاز است که بجای از کار افتادن کامل اپلیکیشن، بتوانیم با پیام‌های درستی مواجه شدن با خطا را نشان دهیم.

Error Handling در این فرایند دقیقا همین نقش را ایفا می‌کند. در مثال‌های بالا ما از فرایند مدیریت خطا استفاده کردیم. حال در بخش‌های بعدی قصد داریم با استفاده از وضعیت کد HTTP که همان response.status است، در مواقع مختلف واکنش‌های متفاوتی به درخواست API بدهیم.

نمونه کد زیر را مشاهده کنید:

const apiUrl = 'https://api.example.com/data';

fetch(apiUrl)
  .then(response => {
    if (!response.ok) {
      if (response.status === 404) {
        throw new Error('Data not found');
      } else if (response.status === 500) {
        throw new Error('Server error');
      } else {
        throw new Error('Network response was not ok');
      }
    }
    return response.json();
  })
  .then(data => {
    outputElement.textContent = JSON.stringify(data, null, 2);
  })
  .catch(error => {
    console.error('Error:', error);
  });

در این مثال ما Status Codeهای ۴۰۴ و ۵۰۰ را بررسی کردیم و براساس نوع هر کدام‌شان، پیام متناسبی را به نمایش گذاشتیم. شما می‌توانید Status Codeهای دیگری را اضافه کنید و همچنین پیام مربوط به هر کدام از این موارد را سفارشی سازی کنید.

چگونه درخواست‌های POST ایجاد کنید

تا به اینجای کار ما روی درخواست‌های GET تمرکز داشته‌ایم و داده‌هایی را از یک منبع خارجی دریافت کرده‌ایم. اما گاهی اوقات نیاز است که از طریق API داده‌هایی را منتقل کنیم. شما می‌توانید این کار را از طریق درخواست‌های POST انجام دهید.

در زیر می‌توانید نمونه‌ای از ایجاد POST Request را با استفاده از دستور fetch مشاهده کنید:

const apiUrl = 'https://api.example.com/data';
const data = {
  name: 'John Doe',
  email: 'johndoe@example.com',
};

const requestOptions = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
};

fetch(apiUrl, requestOptions)
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => {
    outputElement.textContent = JSON.stringify(data, null, 2);
  })
  .catch(error => {
    console.error

('Error:', error);
  });

در این مثال ما کارهای زیر را انجام دادیم:

• ابتدا URLیی که قصد داریم به آن اطلاعات ارسال کنید را مشخص خواهیم کرد.
• در مرحله بعد یک شئ requestOptions را ایجاد کرده‌ایم که متد POST را مشخص می‌کند. همچنین نوع داده‌ای مربوطه را برابر application/json قرار داده‌ایم که قالب JSON را اعمال می‌کند.
• در مرحله بعدی شئ requestOptions را به تابع fetch پاس داده‌ایم.

بقیه کدها دقیقا شبیه به حالت‌های قبلی خود خواهند بود.

چگونه با API Key کار کنیم؟

بسیاری از APIها برای استفاده و دریافت داده از آن‌ها، دسترسی آزاد در اختیار همگان قرار نمی‌دهد بلکه شما باید یک مرحله از احراز هویت را طی کنید تا بتوانید به دیتا مورد نیاز دسترسی داشته باشید. در این شرایط تنها کاربرانی که احراز هویت انجام داده‌اند می‌توانند به داده‌های سرویس خارجی دسترسی پیدا کنند.

برای اینکه فرایند احراز هویت را در درخواست‌های API‌ انجام دهید به چیزی با عنوان Key یا کلید نیاز دارید. در زیر یک نمونه از این حالت را مشاهده خواهید کرد:

const apiKey = 'your_api_key_here';
const apiUrl = 'https://api.example.com/data';

const requestOptions = {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
  },
};

fetch(apiUrl, requestOptions)
  .then(response => {
    if !response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => {
    outputElement.textContent = JSON.stringify(data, null, 2);
  })
  .catch(error => {
    console.error('Error:', error);
  });

در مثال بالا ما یک متغیر با نام apiKey ایجاد کرده‌ایم و مقدار آن را برابر یک رشته ساده قرار داده‌ایم. این متغیر در اصل باید با مقدار کلیدی که سرویس خارجی در اختیارتان قرار می‌دهد مقداردهی شود.

همچنین در فرایند تعریف requestOptions یک سربرگ با نام headers تعریف کرده‌ایم که مقدار Bearer به عنوان پیشوند مربوط به apiKey را نیز اضافه کرده‌ایم. مطمئن شوید که مقدار درستی را به apiKey انتساب می‌کنید در غیر اینصورت API Request شما به درستی انجام نمی‌شود.

یک مثال: دریافت اطلاعات هواشناسی

وبسایت‌های بسیار زیادی هستند که اطلاعات هواشناسی را به صورت API در اختیار توسعه دهندگان قرار می‌دهند. شیوه کاری این وبسایت‌ها به این صورت است که شما یک لوکیشن را وارد وبسایت می‌کنید و بعد از جستجو، اطلاعات مربوط به آب و هوای همان شهر را به شما نشان می‌دهد.

در زیر ما با استفاده از API وبسایت OpenWeatherMap یک درخواست GET را ایجاد کرده‌ایم که ساختار بسیار ساده‌ای دارد.

const apiKey = 'your_openweathermap_api_key';
const apiUrl = `https://api.openweathermap.org/data/2.5/weather?q=London&appid=${apiKey}`;

const outputElement = document.getElementById('weather-output');

fetch(apiUrl)
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => {
    const temperature = data.main.temp;
    const description = data.weather[0].description;
    const location = data.name;
    outputElement.innerHTML = `<p>Temperature in ${location}: ${temperature}°C</p>
                               <p>Weather: ${description}</p>`;
  })
  .catch(error => {
    console.error('Error:', error);
  });

در مثال بالا ما یک درخواست GET را به OpenWeatherMap ارسال کرده‌ایم و API Key مربوطه را نیز در ساختار URL ایجاد کرده‌ایم. در نهایت با انجام دقیق کارها دما و توضیحات مربوط به آب و هوا موقعیت مورد نظر به ما نشان داده خواهد شد.

در پایان

در این مطلب از وبسایت راکت شیوه استفاده از API Request در جاوا اسکریپت را به صورت یک موضوع مقدماتی به شما آموزش دادیم. مطمئنا مواردی که در این مطلب گفته شده‌اند از جمله مهمترین مواردی هستند که توسعه دهندگان جاوا اسکریپت نیاز دارند تا بدانند و با موضوعات مختلف آن آشنا شوند.