امروزه تقریباً هیچ نرمافزاری بدون API کار نمیکند. از سیستمهای پرداخت آنلاین تا پیامرسانها، از دیجیکالا تا گوگل مپ، از سامانههای بانکی تا سرویسهای هوش مصنوعی تمام این ابزارها با API کار میکنند. API به برنامهها اجازه میدهد با یکدیگر صحبت کنند، داده رد و بدل کنند، عملیات انجام دهند و حتی رفتار یکدیگر را کنترل کنند. در این مقاله، قصد داریم نحوه صدا زدن API های خارجی با پایتون را به صورت جامع، کاربردی و مرحلهبهمرحله ارائه کنیم.
در پایتون، محبوبترین و سادهترین کتابخانه برای کار با API، کتابخانهی requests است. دلیل این محبوبیت چند چیز است:
- ساده بودن و خوانایی بالا
- پشتیبانی از همه انواع HTTP Request
- پشتیبانی از Token، Header، Timeout و Session
- مناسب برای محیطهای Production
بخش اول: نصب کتابخانه Requests
برای کار با APIها ابتدا باید کتابخانه Requests را نصب کنید:
pip install requests
کتابخانه Requests امکانات زیر را فراهم میکند:
- ارسال درخواستهای GET, POST, PUT, DELETE
- ارسال Headers
- ارسال Query Parameters
- ارسال Body به صورت JSON یا فرم
- مدیریت Timeout
- مدیریت خطاهای HTTP و شبکه
- پشتیبانی از Session
- پیادهسازی Retry
- احراز هویت Token و Basic Auth
در ادامه تکتک این موارد را بررسی میکنیم.
بخش دوم: اولین درخواست GET
GET سادهترین نوع درخواست است و برای دریافت اطلاعات استفاده میشود.
مثال:
import requests
url = "https://jsonplaceholder.typicode.com/posts"
response = requests.get(url)
print(response.json())
اگر پاسخ ساختار JSON داشته باشد، متد .json() آن را به دیکشنری پایتون تبدیل میکند.
بخش سوم: ارسال Query Parameters
گاهی لازم است اطلاعاتی مثل صفحهبندی، تعداد نتایج، فیلترها و … را همراه درخواست ارسال کنیم.
مثلاً:
https://api.example.com/users?page=2&limit=10
در پایتون:
params = {"page": 2, "limit": 10}
response = requests.get(url, params=params)
کتابخانه requests خودش به طور خودکار پارامترها را به URL اضافه میکند.
بخش چهارم: ارسال Headers
هدِرها بخش مهمی از API هستند؛ مخصوصاً وقتی نیاز به احراز هویت یا اعلام نوع داده دارید.
مثال:
headers = {
"Accept": "application/json",
"User-Agent": "MyPythonApp/1.0"
}
response = requests.get(url, headers=headers)
اگر API نیاز به Token داشته باشد، Token معمولاً داخل Header قرار میگیرد.
بخش پنجم: ارسال POST همراه با JSON
POST برای ایجاد داده در سمت سرور استفاده میشود. مثلاً ثبت کاربر جدید، ایجاد پست، ارسال فرم و…
import requests
url = "https://jsonplaceholder.typicode.com/posts"
data = {
"title": "New Post Title",
"body": "Some text here",
"userId": 1
}
response = requests.post(url, json=data)
print(response.json())
اگر از json= استفاده کنید، پایتون بهطور خودکار داده را تبدیل به JSON کرده و Header مناسب اضافه میکند.
بخش ششم: مدیریت Timeout
در محیطهای واقعی (Production)، همیشه باید Timeout تعیین کنید تا برنامه هنگ نکند.
مثال:
response = requests.get(url, timeout=5)
اگر سرور پاسخ ندهد، درخواست بعد از ۵ ثانیه قطع میشود.
بخش هفتم: مدیریت خطاها به صورت حرفهای
درخواستهای API همیشه ممکن است با خطا مواجه شوند:
- قطع اینترنت
- کندی سرور
- پاسخ HTTP نامعتبر
- خطاهای 404، 500، 503
- تایماوت
- Token اشتباه
بهترین شیوه:
import requests
try:
response = requests.get(url, timeout=5)
response.raise_for_status() # هندل خودکار خطاهای HTTP
data = response.json()
except requests.exceptions.Timeout:
print("خطا: درخواست تایماوت شد.")
except requests.exceptions.ConnectionError:
print("خطا: اتصال برقرار نشد.")
except requests.exceptions.HTTPError as e:
print("خطای HTTP:", e)
except Exception as e:
print("خطای ناشناخته:", e)
متد raise_for_status() اگر کد HTTP خطا باشد (مثل 404 ،401، 500)، خطا ایجاد میکند.
بخش هشتم: استفاده از Session برای بهبود کارایی
اگر قرار است چندین درخواست به یک API بزنید، استفاده از Session خیلی مهم است:
- سرعت بالاتر (Connection Pooling)
- ارسال خودکار Headerهای مشابه
- مدیریت بهتر Token
نمونه:
session = requests.Session()
session.headers.update({
"Accept": "application/json",
"Authorization": "Bearer MY_TOKEN"
})
response = session.get("https://api.example.com/data")
بخش نهم: انواع احراز هویت (Authentication)
1. Bearer Token
سادهترین روش:
headers = {"Authorization": "Bearer YOUR_TOKEN"}
requests.get(url, headers=headers)
2. Basic Auth
مناسب برای APIهای ساده:
response = requests.get(url, auth=("username", "password"))
3. OAuth2 (پیشرفته)
بسیاری از APIهای مدرن مثل Google، GitHub، Discord و… از OAuth2 استفاده میکنند.
در OAuth2:
- ابتدا باید Token بگیرید
- سپس Token را در Header ارسال کنید
- اگر Token منقضی شد باید Refresh Token بگیرید
بخش دهم: Pagination
اگر API داده زیادی داشته باشد، صفحهبندی میشود.
مثال:
def get_all_pages():
page = 1
results = []
while True:
params = {"page": page}
r = requests.get(url, params=params)
data = r.json()
if not data:
break
results.extend(data)
page += 1
return results
بخش یازدهم: مدیریت Rate Limit
اگر بهطور زیاد API را صدا بزنید، ممکن است پیام 429 دریافت کنید:
«Too Many Requests»
راهحل:
import time
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 1))
time.sleep(retry_after)
بخش دوازدهم: Retry اتوماتیک (حرفهای)
برای سرورهای ناپایدار یا اتصالات شکننده، Retry ضروری است.
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
session = requests.Session()
retry_strategy = Retry(
total=5,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)
این یعنی اگر پاسخ HTTP یکی از کدهای بالا باشد، درخواست دوباره ارسال میشود.
بخش سیزدهم: ساخت یک APIClient تمیز و قابل استفاده در پروژهها
این ساختار حرفهای و قابل توسعه است:
import requests
class APIClient:
def __init__(self, base_url, token=None, timeout=5):
self.base_url = base_url
self.session = requests.Session()
self.timeout = timeout
self.session.headers.update({"Accept": "application/json"})
if token:
self.session.headers.update({"Authorization": f"Bearer {token}"})
def get(self, endpoint, params=None):
try:
r = self.session.get(self.base_url + endpoint, params=params, timeout=self.timeout)
r.raise_for_status()
return r.json()
except Exception as e:
print("Error:", e)
return None
def post(self, endpoint, data=None):
try:
r = self.session.post(self.base_url + endpoint, json=data, timeout=self.timeout)
r.raise_for_status()
return r.json()
except Exception as e:
print("Error:", e)
return None
# استفاده:
api = APIClient("https://jsonplaceholder.typicode.com")
print(api.get("/posts")[0])
