API و دریافت داده از API

API (Application Programming Interface) قراردادی است بین سرویس شما و ارائه‌دهنده داده: شما Request می‌فرستید، سرور Response برمی‌گرداند — اغلب JSON. در مقایسه با استخراج داده از وب (Web Scraping)، مسیر API وقتی مجاز و پایدار است معمولاً هزینه نگهداری کمتری دارد.

API چیست؟

به‌جای اینکه HTML صفحه را parse کنید، فیلدهای تایپ‌شده می‌گیرید. برای محصول داده‌محور، versioning API (/v2/) و changelog ارائه‌دهنده مهم است.

Request و Response

Request شامل URL، متد HTTP، Headers (مثلاً Authorization، Accept: application/json) و گاهی body (در POST). Response شامل status code، headers و body است.

احراز هویت

API Key

رایج در سرویس‌های B2B؛ در header یا query — ترجیحاً header.

Bearer Token

Authorization: Bearer <token>؛ expiry را مانیتور کنید.

OAuth (مفهومی)

برای دسترسی کاربر نهایی؛ refresh token در vault.

JSON و schema

پاسخ را به dict پایتون parse کنید و با schema (مثلاً Pydantic) validate کنید. فیلد اضافه نادیده، فیلد اجباری گم‌شده → alert.

Pagination

الگوها: ?page=2، cursor=abc، یا لینک next در JSON. حلقه تا خالی شدن صفحه — مشابه pagination در scrape اما قراردادمندتر.

محدودیت تعداد درخواست (Rate Limit)

سرور با ۴۲۹ یا header X-RateLimit-Remaining اعلام می‌کند. client شما باید throttle و صف داشته باشد — نه hammer کردن endpoint.

Retry، Timeout و مدیریت خطا

timeout ثابت (مثلاً ۳۰ ثانیه). retry فقط برای خطاهای گذرا (۵۰۳، شبکه) با exponential backoff. ۴۰۰ را retry نکنید — bug client است.

Webhook

push رویداد به URL شما — جزئیات در راهنمای Webhook.

REST API

بیشتر APIهای عمومی REST هستند: resource + HTTP verb. GraphQL/gRPC در enterprise دیده می‌شود؛ اصل «قرارداد + version» همان است.

مثال Python با requests

import os
import time
import requests

URL = "https://api.example.com/v1/prices"
HEADERS = {"Authorization": f"Bearer {os.environ['API_TOKEN']}"}

for page in range(1, 100):
    resp = requests.get(URL, headers=HEADERS, params={"page": page}, timeout=30)
    if resp.status_code == 429:
        time.sleep(int(resp.headers.get("Retry-After", 60)))
        continue
    resp.raise_for_status()
    batch = resp.json().get("items", [])
    if not batch:
        break
    # ذخیره batch در DB یا فایل

فرض: pagination صفحه‌ای و token در env. در production logging و idempotency کلید یکتا اضافه کنید.

مثال سناریو: قیمت / CRM

{
  "items": [
    {"sku": "A12", "price_irr": 12500000, "updated_at": "2026-03-19T10:00:00Z"}
  ],
  "page": 1,
  "has_next": true
}

نمونه نمایشی — ساختار JSON

API در برابر Web Scraping

مقایسه intent در مقاله جداگانه. خلاصه: API برای قرارداد رسمی؛ scrape وقتی UI منبع حقیقت است یا API ناقص است.

API در برابر دسترسی مستقیم به Database

DB مستقیم فقط با مجوز و شبکه امن؛ API لایه کنترل، audit و rate limit است. در پروژه مشتری اغلب API gateway می‌سازید نه expose DB.

اگر API داشته باشیم، همیشه scrape لازم نیست؟

نه همیشه. گاهی API فیلد marketing ندارد، یا تأخیر دارد، یا sandbox با production فرق دارد. trade-off واقعی بین پوشش، هزینه، مجوز و پایداری است.

Client مقاوم در production

timeout جدا، log correlation id، circuit breaker، ذخیره raw response برای debug (بدون PII). مسیر scrape: API در برابر Scraping.

سوالات متداول

قدم بعدی

راهنمای جامع وب‌اسکرپینگ، زمان‌بندی وظایف، سرویس توسعه API.