API چیست؟ آموزش کار با API‌ها در جاوااسکریپت با استفاده از Fetch

وقتی صحبت از توسعه نرم‌افزار و وب می‌شود، یکی از واژه‌هایی که زیاد شنیده‌ایم API است. اما API دقیقاً چیست و چرا این‌قدر مهم است؟ تصور کنید می‌خواهید از طریق یک اپلیکیشن موبایل غذای مورد علاقه‌تان را سفارش دهید. اپلیکیشن شما باید با سرور رستوران ارتباط برقرار کند، منو را دریافت کند، سفارش شما را ثبت کند و وضعیت تحویل را برگرداند. این ارتباط پشت‌صحنه توسط API انجام می‌شود؛ یعنی رابطی که دو نرم‌افزار را قادر می‌سازد بدون نیاز به دانستن جزئیات داخلی یکدیگر، با هم صحبت کنند.

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

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

API چیست؟

API یا Application Programming Interface در ساده‌ترین تعریف، یک رابط ارتباطی بین نرم‌افزارهاست. به‌جای اینکه دو برنامه مجبور باشند جزئیات داخلی یکدیگر را بدانند، API مجموعه‌ای از قوانین و قراردادها را فراهم می‌کند تا بتوانند داده‌ها و قابلیت‌ها را با هم به اشتراک بگذارند.

مثال ساده

فرض کنید در یک رستوران نشسته‌اید. شما غذا را انتخاب می‌کنید، اما مستقیم وارد آشپزخانه نمی‌شوید. سفارش خود را به گارسون می‌دهید و او با دانستن قوانین و منو، درخواست شما را به آشپزخانه منتقل می‌کند و نتیجه (غذا) را برایتان می‌آورد. در این مثال، گارسون همان API است.

انواع API:

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

چرا وب APIها مهم هستند؟

• دسترسی به داده‌های خارجی (آب‌وهوا، اخبار، شبکه‌های اجتماعی).
• اتصال سرویس‌های مختلف به یکدیگر (مثلاً پرداخت آنلاین یا نقشه گوگل).
• ساده‌سازی توسعه: به‌جای ساخت همه‌چیز از ابتدا، می‌توان از سرویس‌های آماده استفاده کرد.

آشنایی با HTTP و درخواست‌ها

برای اینکه بتوانیم با یک API کار کنیم، باید زبان مشترک ارتباطی را بشناسیم. در وب این زبان همان HTTP (Hypertext Transfer Protocol) است. هر بار که مرورگر شما صفحه‌ای را باز می‌کند یا جاوااسکریپت داده‌ای را از سرور می‌گیرد، در واقع یک درخواست HTTP ارسال می‌شود و پاسخی دریافت می‌کند.

ساختار یک درخواست HTTP:

• URL (نشانی): مشخص می‌کند درخواست به کدام سرور و مسیر فرستاده شود.
• Method (متد): نوع عملیات را تعیین می‌کند.
• Headers (هدرها): اطلاعات اضافی مثل نوع داده یا کلید دسترسی.
• Body (بدنه): داده‌ای که همراه درخواست ارسال می‌شود (مثلاً در متد POST).

متدهای رایج HTTP:

• GET: دریافت داده از سرور (مثلاً گرفتن لیست کاربران).
• POST: ارسال داده به سرور (مثلاً ثبت کاربر جدید).
• PUT/PATCH: به‌روزرسانی داده موجود.
• DELETE: حذف داده.

ساختار پاسخ HTTP:

• Status Code (کد وضعیت): عددی که نتیجه درخواست را نشان می‌دهد (۲۰۰ موفق، ۴۰۴ پیدا نشد، ۵۰۰ خطای سرور).
• Headers: اطلاعاتی درباره پاسخ (نوع داده، طول محتوا).
• Body: داده اصلی که سرور برمی‌گرداند (مثلاً JSON یا HTML).

شناخت این مفاهیم پایه‌ای ضروری است، چون Fetch در جاوااسکریپت دقیقاً همین درخواست‌ها و پاسخ‌ها را مدیریت می‌کند.

معرفی Fetch در جاوااسکریپت

تا همین چند سال پیش، توسعه‌دهندگان برای ارتباط با سرور و دریافت داده‌ها از XMLHttpRequest (XHR) استفاده می‌کردند. این روش اگرچه کارآمد بود، اما کدنویسی آن پیچیده و پر از جزئیات اضافی بود. برای همین، جاوااسکریپت مدرن ابزاری ساده‌تر و قدرتمندتر معرفی کرد: Fetch API.

ویژگی‌های کلیدی Fetch:

• Promise-based: به‌جای استفاده از callbackهای تو در تو، Fetch از Promise استفاده می‌کند که خوانایی و مدیریت خطا را ساده‌تر می‌سازد.
• ساده و مدرن: سینتکس کوتاه‌تر و قابل فهم‌تر نسبت به XHR.
• انعطاف‌پذیر: امکان ارسال انواع درخواست‌ها (GET ،POST ،PUT ،DELETE) و مدیریت هدرها و بدنه درخواست.
• پشتیبانی از async/await: می‌توان به‌صورت همگام‌نما (synchronous-like) کد نوشت که بسیار خواناتر است.

نمونه ساده استفاده از Fetch:

fetch('https://api.example.com/data')
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

در این مثال:

• fetch یک درخواست GET به آدرس مشخص‌شده ارسال می‌کند.
• response.json() داده دریافتی را به فرمت JSON تبدیل می‌کند.
• در نهایت داده در کنسول چاپ می‌شود.
• اگر خطایی رخ دهد، در بخش catch مدیریت می‌شود.

این سادگی و خوانایی باعث شده Fetch به استاندارد اصلی برای کار با APIها در جاوااسکریپت تبدیل شود.

مثال واقعی

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    // بررسی وضعیت پاسخ
    if (!response.ok) {
      throw new Error('خطا در دریافت داده');
    }
    return response.json(); // تبدیل پاسخ به JSON
  })
  .then(data => {
    console.log('داده دریافت شد:', data);
  })
  .catch(error => {
    console.error('مشکل رخ داد:', error);
  });

ارسال داده با Fetch (POST)

تا اینجا دیدیم که چگونه می‌توان با متد GET داده‌ها را از یک API دریافت کرد. اما در بسیاری از موارد لازم است داده‌ای را به سرور ارسال کنیم؛ مثلاً ثبت کاربر جدید یا ذخیره یک فرم. برای این کار از متد POST استفاده می‌کنیم.

نمونه کد ارسال داده با Fetch:

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Fetch Tutorial',
    body: 'This is a sample POST request',
    userId: 1
  })
})
  .then(response => {
    if (!response.ok) {
      throw new Error('Error sending data');
    }
    return response.json();
  })
  .then(data => {
    console.log('Server response:', data);
  })
  .catch(error => {
    console.error('An error occurred:', error);
  });

توضیح خط به خط:

• method: 'POST': تعیین می‌کند که درخواست از نوع POST باشد.
• headers: مشخص می‌کند داده‌ای که ارسال می‌کنیم از نوع JSON است.
• body: داده‌ای که باید به سرور فرستاده شود، با JSON.stringify به رشته JSON تبدیل می‌شود.
• سپس پاسخ سرور بررسی و در صورت موفقیت در کنسول نمایش داده می‌شود.

این الگو پایه‌ای برای ارسال داده به هر API است. در پروژه‌های واقعی، معمولاً نیاز به ارسال توکن احراز هویت یا اطلاعات بیشتر در هدرها داریم.

مدیریت خطاها و وضعیت پاسخ

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

کد نمونه برای بررسی وضعیت پاسخ:

fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      // بررسی وضعیت پاسخ
      throw new Error(`Request failed with status ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error occurred:', error.message);
  });

نکات کلیدی:

• response.ok: اگر وضعیت پاسخ بین 200 تا 299 باشد، مقدار آن true است.
• response.status: عدد وضعیت پاسخ را برمی‌گرداند (مثلاً 404 برای "پیدا نشد").
• مدیریت خطا با catch: هرگونه خطا در شبکه یا پردازش پاسخ در این بخش گرفته می‌شود.
• نمایش پیام مناسب: بهتر است پیام خطا برای کاربر قابل فهم باشد، نه صرفاً یک متن فنی.

چرا این مهم است؟

• در پروژه‌های واقعی ممکن است سرور در دسترس نباشد یا داده نامعتبر برگرداند.
• مدیریت خطا باعث می‌شود تجربه کاربری بهتر شود و برنامه پایدارتر عمل کند.

مثال واقعی کار با OpenWeather

برای اینکه کار با APIها ملموس‌تر شود، بیایید یک مثال واقعی با سرویس OpenWeatherMap پیاده‌سازی کنیم. این سرویس داده‌های آب‌وهوا را در اختیار توسعه‌دهندگان قرار می‌دهد و برای استفاده از آن باید ابتدا در سایت OpenWeather ثبت‌نام کرده و یک API Key دریافت کنید.

نمونه کد: دریافت وضعیت آب‌وهوا با Fetch

در این مثال، وضعیت آب‌وهوای شهر تهران را از OpenWeather دریافت می‌کنیم:

const apiKey = 'YOUR_API_KEY'; // کلید اختصاصی شما
const city = 'Tehran';
const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`;

fetch(url)
  .then(response => {
    if (!response.ok) {
      throw new Error(`Request failed with status ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(`Weather in ${data.name}:`);
    console.log(`Temperature: ${data.main.temp}°C`);
    console.log(`Condition: ${data.weather[0].description}`);
  })
  .catch(error => {
    console.error('Error occurred:', error.message);
  });

توضیح:

• apiKey: کلید اختصاصی که از OpenWeather دریافت می‌کنید.
• q=${city}: نام شهری که می‌خواهید وضعیت آب‌وهوای آن را بگیرید.
• units=metric: دما را بر حسب سانتی‌گراد نمایش می‌دهد.
• پاسخ شامل اطلاعاتی مثل دما (main.temp)، شرایط آب‌وهوا (weather[0].description) و نام شهر است.

تمرین پیشنهادی:

• شهر را به انتخاب کاربر تغییر دهید (مثلاً از طریق یک input در HTML).
• علاوه بر دما، رطوبت (main.humidity) و سرعت باد (wind.speed) را هم نمایش دهید.
• داده‌ها را به‌جای کنسول، در صفحه HTML نمایش دهید.

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

جمع‌بندی

در این مطلب قدم‌به‌قدم دیدیم که API چیست و چرا در توسعه نرم‌افزار و وب اهمیت دارد. سپس با ساختار درخواست‌های HTTP آشنا شدیم و یاد گرفتیم چگونه با استفاده از Fetch API در جاوااسکریپت داده‌ها را دریافت (GET) و ارسال (POST) کنیم. همچنین بررسی کردیم که مدیریت خطاها و وضعیت پاسخ چقدر برای پایداری و تجربه کاربری اهمیت دارد و در نهایت یک تمرین عملی انجام دادیم تا مفاهیم را در عمل لمس کنیم.