راهنمای جامع کار با API در پایتون

مقدمه

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

API چیست؟

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

انواع رایج API

• API وب (Web API): رایج‌ترین نوع API است که از طریق HTTP/HTTPS داده‌ها را ارسال و دریافت می‌کند (مانند REST، GraphQL).
• API سیستمی: برای ارتباط با سیستم‌عامل یا سخت‌افزار (مانند API ویندوز).
• API کتابخانه‌ای: برای استفاده داخلی در پروژه‌ها یا ماژول‌ها.

HTTP و نقش آن در ارتباط با API

بیشتر APIهای مدرن بر بستر پروتکل HTTP کار می‌کنند. درخواست‌هایی مثل GET، POST، PUT، PATCH و DELETE برای ارتباط با داده‌ها مورد استفاده قرار می‌گیرند.

کتابخانه‌های پایتون برای کار با API

محبوب‌ترین و پراستفاده‌ترین کتابخانه برای کار با APIهای وب در پایتون، کتابخانه requests است. اما کتابخانه‌های دیگری مانند http.client (در کتابخانه استاندارد پایتون)، urllib3 و ابزارهایی برای APIهای خاص نیز وجود دارند.

نصب و معرفی requests

کتابخانه requests یکی از ساده‌ترین راه‌ها برای ارسال و دریافت داده از طریق HTTP است.
برای نصب:

pip install requests

نمونه عملی: دریافت داده از یک API عمومی

در این بخش با یک مثال ساده دریافت داده از یک API عمومی را بررسی می‌کنیم.
فرض کنید می‌خواهید اطلاعات تصادفی از یک کاربر فرضی (با استفاده از سایت https://randomuser.me/api/) را دریافت کنید.

import requests
url = 'https://randomuser.me/api/'
response = requests.get(url)
print(response.json())

در این مثال، متد get برای ارسال درخواست استفاده شده و داده دریافتی با متد json() نمایش داده می‌شود.

ارسال داده با متد POST

برخی APIها برای افزودن یا ثبت داده، نیازمند متد POST هستند. مثال زیر نحوه ارسال داده با POST را نشان می‌دهد:

import requests
url = 'https://jsonplaceholder.typicode.com/posts'
data = {'title': 'foo', 'body': 'bar', 'userId': 1}
response = requests.post(url, json=data)
print(response.json())

در این مثال، داده به صورت JSON به API ارسال شده و پاسخ نمایش داده می‌شود.

ارسال Header و توکن احراز هویت

بسیاری از APIها برای دسترسی نیاز به احراز هویت دارند. معمول‌ترین روش، استفاده از توکن در Header است.

headers = {'Authorization': 'Bearer YOUR_TOKEN'}
response = requests.get('https://api.example.com/data', headers=headers)

با قراردادن توکن در هدر، به داده‌های محافظت‌شده دسترسی خواهید داشت.

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

در ارتباط با APIها همواره باید احتمال خطا را لحاظ کنید؛ مانند نبود اتصال، تایم‌اوت، یا دریافت پیامی با وضعیت خطا (کدهای HTTP 400 و 500 و …).

نمونه مدیریت خطا:

try:
    response = requests.get('https://randomuser.me/api/', timeout=5)
    response.raise_for_status()  # در صورت کد خطا، استثنا ایجاد می‌کند
    data = response.json()
except requests.exceptions.RequestException as e:
    print('Request failed:', e)

ارسال پارامترهای URL به API

گاهی نیاز است پارامتر (مانند query string) به درخواست اضافه کنید:

params = {'results': 5, 'gender': 'female'}
response = requests.get('https://randomuser.me/api/', params=params)
print(response.json())

در این مثال، درخواست ۵ کاربر خانم را از API دریافت می‌کند.

پرداختن به ساختار پاسخ (Response)

پاسخ یک API معمولاً به صورت دادهٔ JSON است. کتابخانه requests به راحتی با متد json() محتوای پاسخ را به دیکشنری پایتون تبدیل می‌کند.

• response.status_code: وضعیت پاسخ را نمایش می‌دهد (مثلاً 200 برای موفقیت)
• response.headers: سرآیندهای پاسخ
• response.text: بدنهٔ پاسخ به صورت رشته متنی

مثال:

if response.status_code == 200:
    data = response.json()
    print('Name:', data["results"][0]["name"])
else:
    print('Failed:', response.status_code)

کار با APIهای پیچیده‌تر و پرداختن به OAuth 2.0

بسیاری از APIهای مدرن برای امنیت از استاندارد OAuth 2.0 استفاده می‌کنند. این روش احراز هویت چند مرحله‌ای و دریافت توکن (Access Token) است. کتابخانه requests-oauthlib کار را برای توسعه‌دهندگان ساده می‌کند.
می‌توانید با نصب این کتابخانه و مستندات هر API، به روش صحیح به آن متصل شوید.

کتابخانه‌های پیشرفته برای APIهای خاص

برای سرویس‌هایی مانند توییتر، گوگل و … معمولاً کتابخانه‌های ویژه‌ای وجود دارد (مانند Tweepy برای توییتر، google-api-python-client برای گوگل). این کتابخانه‌ها همه پیچیدگی‌های احراز هویت و مدل داده‌ای را پوشش می‌دهند.

نمونه پروژه کوچک: دریافت و ذخیره داده از یک API

در این پروژه ساده، داده‌های چند کاربر از API randomuser.me گرفته و در یک فایل ذخیره می‌شود.

import requests
import json
params = {'results': 10}
response = requests.get('https://randomuser.me/api/', params=params)
if response.status_code == 200:
    users = response.json()['results']
    with open('users.json', 'w') as f:
        json.dump(users, f, indent=4)
    print('ذخیره شد')
else:
    print('خطا در دریافت داده')

این کد داده‌های ۱۰ نفر را دریافت و به صورت فایل JSON ذخیره می‌کند.

جمع‌بندی

ارتباط با API در پایتون به کمک کتابخانه‌هایی مانند requests بسیار ساده است. با دانستن نحوه ارسال درخواست، مدیریت خطا، ارسال هدر و پارامتر، کار با JSON و پردازش داده‌ها می‌توانید تقریباً به هر سرویسی متصل شوید.
کار با API نه تنها دریچه‌ای رو به داده‌های عظیم اینترنت می‌گشاید، بلکه برای اتوماسیون و ساخت پروژه‌های جذاب و کاربردی نقش کلیدی ایفا می‌کند.

منابع بیشتر

• مستندات requests
• آموزش کار با API در پایتون (Real Python)
• Postman (برای تست API)