آموزش و راهنما

HTTP چیست؟ آموزش Request، Response، Method، Header و Status Code

در این راهنمای عملی با پروتکل HTTP، ساختار Request و Response، متدهای GET و POST، Headerها، Status Codeها، HTTPS و عیب‌یابی API آشنا می‌شوید و یک درخواست واقعی به API درواره ارسال می‌کنید.

HTTP یکی از بنیادی‌ترین مفاهیم برنامه‌نویسی وب و توسعه API است. هر بار که صفحه‌ای را در مرورگر باز می‌کنید، یک اپلیکیشن موبایل اطلاعاتی از Backend می‌گیرد یا برنامه‌ای به API هوش مصنوعی متصل می‌شود، معمولاً یک یا چند پیام HTTP میان Client و Server جابه‌جا می‌شود.

شناخت HTTP فقط برای توسعه‌دهندگان Backend ضروری نیست. برنامه‌نویسان Frontend، موبایل، DevOps، Data Science و هوش مصنوعی نیز برای استفاده درست از APIها باید با Request، Response، Method، Header، Status Code، Timeout و شیوه عیب‌یابی ارتباط HTTP آشنا باشند.

در این آموزش یاد می‌گیریم:

HTTP چیست و چگونه کار می‌کند؟
Client و Server چه نقشی دارند؟
URL و Endpoint از چه بخش‌هایی ساخته می‌شوند؟
HTTP Request شامل چه اطلاعاتی است؟
HTTP Response چگونه تفسیر می‌شود؟
تفاوت GET، POST، PUT، PATCH و DELETE چیست؟
مهم‌ترین Status Codeهای HTTP کدام‌اند؟
Headerهایی مانند Content-Type و Authorization چه کاربردی دارند؟
تفاوت HTTP و HTTPS چیست؟
HTTP/1.1، HTTP/2 و HTTP/3 چه تفاوتی دارند؟
Timeout، Retry و Rate Limit چگونه مدیریت می‌شوند؟
Streaming در API هوش مصنوعی چگونه کار می‌کند؟
چگونه با cURL، Python و JavaScript درخواست HTTP ارسال کنیم؟
چگونه یک درخواست واقعی به API هوش مصنوعی درواره بفرستیم؟

پاسخ کوتاه: HTTP چیست؟

HTTP مخفف عبارت زیر است:

Hypertext Transfer Protocol

HTTP یک پروتکل لایه Application برای انتقال پیام میان Client و Server است. Client یک Request ارسال می‌کند و Server پس از پردازش، یک Response برمی‌گرداند.

فرایند ساده:

Client
  ↓ HTTP Request
Server
  ↓ HTTP Response
Client

برای مثال، مرورگر درخواست زیر را ارسال می‌کند:

GET /articles HTTP/1.1
Host: example.com
Accept: text/html

Server ممکن است پاسخ دهد:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!doctype html>
<html>
  <body>Articles</body>
</html>

مطابق راهنمای HTTP در MDN، HTTP یک پروتکل Client-Server است؛ پیام ارسال‌شده از Client درخواست یا Request و پاسخ Server، Response نام دارد.

پروتکل چیست؟

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

اگر دو برنامه بخواهند با یکدیگر ارتباط برقرار کنند، باید درباره موارد زیر توافق داشته باشند:

ساختار پیام
نحوه شروع ارتباط
نوع عملیات
فرمت داده
روش اعلام موفقیت یا خطا
نحوه پایان یا ادامه ارتباط

HTTP همین قواعد را برای ارتباط در وب و بسیاری از APIها تعریف می‌کند.

Client چیست؟

Client برنامه‌ای است که Request را آغاز می‌کند.

نمونه‌های Client:

مرورگر
اپلیکیشن موبایل
برنامه Python
Frontend نوشته‌شده با JavaScript
ابزار cURL
Postman
سرویس Backend دیگر
دستگاه اینترنت اشیا
برنامه متصل به API هوش مصنوعی

برای HTTP مهم نیست Client حتماً مرورگر باشد. هر برنامه‌ای که Request معتبر ارسال کند می‌تواند Client باشد.

Server چیست؟

Server درخواست را دریافت، پردازش و پاسخ مناسب را برمی‌گرداند.

Server ممکن است:

فایل HTML برگرداند.
اطلاعاتی از دیتابیس بخواند.
داده JSON تولید کند.
کاربر را احراز هویت کند.
فایل ذخیره کند.
یک مدل هوش مصنوعی را فراخوانی کند.
درخواست را به سرویس دیگری هدایت کند.
نتیجه پردازش را Streaming کند.
خطای مناسب برگرداند.

از دید Client، Server معمولاً از طریق یک Host و Port در دسترس است، اما پشت آن می‌تواند چندین سرویس، Load Balancer، Cache، Worker و دیتابیس قرار گرفته باشد.

مدل Request و Response

HTTP معمولاً بر اساس چرخه Request و Response کار می‌کند:

Client آدرس مقصد را مشخص می‌کند.
اتصال شبکه برقرار می‌شود.
Client یک HTTP Request می‌فرستد.
Server درخواست را دریافت می‌کند.
Server عملیات موردنظر را انجام می‌دهد.
Server یک HTTP Response برمی‌گرداند.
Client Status Code، Header و Body را پردازش می‌کند.
اتصال بسته یا برای درخواست بعدی استفاده می‌شود.

یک Request می‌تواند بدون Body باشد، اما همیشه شامل Method و مقصد است.

یک Response نیز ممکن است Body نداشته باشد؛ برای مثال پاسخ 204 No Content.

HTTP Stateless است یعنی چه؟

HTTP ذاتاً Stateless است؛ یعنی هر Request به‌صورت مستقل تفسیر می‌شود و پروتکل به‌تنهایی وضعیت درخواست قبلی را به خاطر نمی‌سپارد.

فرض کنید Client این دو درخواست را ارسال کند:

GET /cart HTTP/1.1

POST /cart/items HTTP/1.1

برای اینکه Server بداند هر دو درخواست متعلق به یک کاربر هستند، باید از سازوکاری مانند این موارد استفاده شود:

Cookie
Session ID
Access Token
API Key
داده ذخیره‌شده سمت Server

Stateless بودن به معنی نداشتن Session در وب نیست؛ بلکه Session باید با مکانیزمی بالاتر از هسته HTTP ساخته شود.

URL چیست؟

URL آدرس یک Resource در شبکه است.

نمونه:

https://api.darvareh.ir/v1/chat/completions

بخش‌های اصلی:

https://api.darvareh.ir/v1/chat/completions
│       │                │
│       │                └── Path
│       └── Host
└── Scheme

Scheme

نحوه ارتباط را مشخص می‌کند:

http
https

Host

نام دامنه یا IP مقصد:

api.darvareh.ir

Port

اگر Port صریح نوشته نشده باشد، مقدار پیش‌فرض بر اساس Scheme استفاده می‌شود:

HTTP  → 80
HTTPS → 443

نمونه دارای Port:

http://localhost:8000

Path

Resource یا Endpoint موردنظر را مشخص می‌کند:

/v1/chat/completions

Query String

برای ارسال پارامترهای تکمیلی در URL استفاده می‌شود:

https://api.example.com/v1/items?page=2&limit=20

در این مثال:

page=2
limit=20

Query Parameter هستند.

Fragment

بخش مشخصی از یک سند را در Client تعیین می‌کند:

https://example.com/guide#installation

Fragment معمولاً در HTTP Request به Server ارسال نمی‌شود و در سمت Client پردازش می‌شود.

Endpoint چیست؟

Endpoint ترکیبی از HTTP Method و مسیر مشخصی است که یک عملیات را ارائه می‌دهد.

این دو Endpoint یکسان نیستند:

GET /v1/models
POST /v1/models

حتی اگر Path یکسان باشد، Method می‌تواند معنای عملیات را تغییر دهد.

نمونه Endpoint چت درواره:

POST https://api.darvareh.ir/v1/chat/completions

در این Endpoint:

Method برابر POST است.
Host برابر api.darvareh.ir است.
Path برابر /v1/chat/completions است.
Body شامل Model ID، Messages و تنظیمات تولید می‌شود.

ساختار HTTP Request

یک Request معمولاً از این بخش‌ها تشکیل می‌شود:

Request Line
Headerها
خط خالی
Body اختیاری

نمونه:

POST /v1/chat/completions HTTP/1.1
Host: api.darvareh.ir
Authorization: Bearer YOUR_DARVAREH_API_KEY
Content-Type: application/json
Accept: application/json

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "HTTP چیست؟"
    }
  ]
}

Request Line

اولین خط درخواست:

POST /v1/chat/completions HTTP/1.1

از سه بخش ساخته شده است:

Method + Path + HTTP Version

در HTTP/2 و HTTP/3 نمایش سطح شبکه متفاوت است، اما مفاهیم Method، مسیر، Header و Body همچنان وجود دارند.

HTTP Header چیست؟

Header اطلاعات تکمیلی درباره Request یا Response را منتقل می‌کند.

نمونه:

Content-Type: application/json

هر Header از نام و مقدار تشکیل می‌شود:

Header-Name: Header-Value

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

نوع محتوا
احراز هویت
فرمت قابل قبول پاسخ
زبان
Cache
اندازه محتوا
فشرده‌سازی
Origin
شناسه درخواست
زمان Retry
Location
Cookie

HTTP Body چیست؟

Body محتوای اصلی Request یا Response است.

نمونه Body از نوع JSON:

{
  "name": "Ali",
  "active": true
}

نمونه Body متنی:

Hello World

نمونه Body فرم:

name=Ali&active=true

نمونه Body فایل نیز می‌تواند داده Binary باشد.

Methodهایی مانند POST، PUT و PATCH معمولاً Body دارند. GET معمولاً بدون Body استفاده می‌شود و برای ارسال پارامترها از Query String بهره می‌گیرد.

ساختار HTTP Response

یک Response معمولاً از این بخش‌ها تشکیل می‌شود:

Status Line
Headerها
خط خالی
Body اختیاری

نمونه:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 82

{
  "id": 125,
  "status": "completed",
  "message": "Request processed successfully"
}

Status Line

اولین خط پاسخ:

HTTP/1.1 200 OK

شامل این بخش‌ها است:

HTTP Version + Status Code + Reason Phrase

مهم‌ترین قسمت برای برنامه، Status Code عددی است. Reason Phrase توضیح کوتاهی برای خوانایی انسان است و نباید منطق برنامه به متن آن وابسته باشد.

HTTP Method چیست؟

Method یا Verb مشخص می‌کند Client چه عملیاتی از Server می‌خواهد.

متدهای رایج:

GET
POST
PUT
PATCH
DELETE
HEAD
OPTIONS

فهرست و تعریف استاندارد Methodها در مرجع HTTP Methods در MDN ارائه شده است.

متد GET

برای دریافت Resource استفاده می‌شود.

نمونه:

GET /v1/models HTTP/1.1
Host: api.darvareh.ir
Authorization: Bearer YOUR_DARVAREH_API_KEY
Accept: application/json

کاربردهای رایج:

دریافت فهرست
خواندن اطلاعات یک Resource
جست‌وجو
دریافت فایل
بررسی وضعیت

نمونه‌ها:

GET /users
GET /users/125
GET /products?category=software

در طراحی معمول API، GET نباید وضعیت Resource را تغییر دهد.

متد POST

برای ارسال داده و ایجاد یا شروع یک عملیات استفاده می‌شود.

نمونه:

POST /v1/chat/completions HTTP/1.1
Host: api.darvareh.ir
Content-Type: application/json

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "سلام"
    }
  ]
}

کاربردها:

ایجاد Resource
ثبت فرم
شروع پردازش
تولید پاسخ مدل
آپلود
اجرای عملیات

POST لزوماً Idempotent نیست. ارسال دوباره یک Request ممکن است عملیات را دوباره انجام دهد.

متد PUT

معمولاً برای جایگزینی کامل Resource در یک URI مشخص استفاده می‌شود.

نمونه:

PUT /users/125 HTTP/1.1
Content-Type: application/json

{
  "name": "Sara",
  "email": "sara@example.com",
  "active": true
}

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

متد PATCH

برای تغییر بخشی از Resource استفاده می‌شود.

PATCH /users/125 HTTP/1.1
Content-Type: application/json

{
  "active": false
}

در این مثال فقط فیلد active تغییر می‌کند.

PUT و PATCH را صرفاً براساس نام آن‌ها پیاده‌سازی نکنید. قرارداد دقیق بدنه، فیلدهای حذف‌شده و رفتار مقدار null باید مستند باشد.

متد DELETE

برای حذف Resource استفاده می‌شود:

DELETE /users/125 HTTP/1.1

پاسخ ممکن است 204 No Content یا یک پاسخ JSON باشد. رفتار حذف نرم، حذف دائمی و امکان بازیابی باید در مستندات API مشخص شود.

متد HEAD

مانند GET است، اما Server نباید Body پاسخ Resource را ارسال کند.

کاربردها:

بررسی وجود Resource
مشاهده Metadata
بررسی Content-Length
بررسی Last-Modified
بررسی Cache

متد OPTIONS

برای دریافت اطلاعات درباره گزینه‌های ارتباطی یا Methodهای پشتیبانی‌شده استفاده می‌شود.

در Browser، درخواست‌های CORS Preflight ممکن است با OPTIONS ارسال شوند.

Safe Method چیست؟

Safe Method متدی است که هدف تعریف‌شده آن تغییر وضعیت Server نیست.

نمونه‌های رایج:

GET
HEAD
OPTIONS

Safe بودن به معنی رایگان، بدون Log یا بدون مصرف منابع بودن نیست. یک GET می‌تواند محاسبه سنگینی انجام دهد، اما نباید با هدف تغییر داده طراحی شود.

Idempotent Method چیست؟

یک عملیات Idempotent است اگر چند بار اجرای Request یکسان، اثر موردنظر نهایی مشابه یک بار اجرا را داشته باشد.

متدهای معمولاً Idempotent:

GET
HEAD
PUT
DELETE
OPTIONS

POST معمولاً Idempotent در نظر گرفته نمی‌شود. PATCH نیز لزوماً Idempotent نیست.

برای مثال، این عملیات با هر بار اجرا موجودی را افزایش می‌دهد و Idempotent نیست:

POST /wallet/add-credit

اما جایگزین‌کردن وضعیت Resource با مقدار ثابت می‌تواند Idempotent باشد:

PUT /users/125/status

Idempotent بودن به معنی یکسان‌بودن Status Code یا متن تمام پاسخ‌ها نیست؛ بحث درباره اثر موردنظر روی Server است.

مهم‌ترین HTTP Status Codeها

Status Code نتیجه پردازش Request را به Client اعلام می‌کند.

کدها در پنج گروه قرار می‌گیرند:

گروه	مفهوم
`1xx`	اطلاعاتی
`2xx`	موفقیت
`3xx`	هدایت یا Cache
`4xx`	مشکل در Request یا دسترسی Client
`5xx`	خطای Server یا سرویس بالادستی

فهرست کامل در مرجع HTTP Status Codeهای MDN قرار دارد.

کد 200 OK

Request با موفقیت پردازش شده است:

HTTP/1.1 200 OK

معمولاً برای GET موفق یا عملیاتی که پاسخ دارد استفاده می‌شود.

کد 201 Created

Resource جدید با موفقیت ساخته شده است:

HTTP/1.1 201 Created
Location: /users/126

Header مربوط به Location می‌تواند آدرس Resource ساخته‌شده را مشخص کند.

کد 202 Accepted

Request پذیرفته شده، اما پردازش هنوز کامل نشده است:

HTTP/1.1 202 Accepted

برای Jobهای Async یا پردازش طولانی مناسب است. این کد موفقیت نهایی عملیات را تضمین نمی‌کند و Client باید وضعیت Job را بعداً بررسی کند.

کد 204 No Content

عملیات موفق بوده، اما پاسخ Body ندارد:

HTTP/1.1 204 No Content

Client نباید تلاش کند Body خالی را به JSON تبدیل کند.

کد 301 Moved Permanently

Resource به‌صورت دائمی به URL دیگری منتقل شده است.

کد 302 Found

معمولاً Redirect موقت را نشان می‌دهد. رفتار Method پس از Redirect در Clientهای مختلف و تاریخچه HTTP پیچیدگی‌هایی دارد.

برای حفظ دقیق Method و Body در Redirectهای موقت و دائم، کدهای 307 و 308 معنای روشن‌تری دارند.

کد 304 Not Modified

در Conditional Request و Cache استفاده می‌شود. Server اعلام می‌کند نسخه Client هنوز معتبر است و نیازی به ارسال مجدد Body نیست.

304 به معنی خطا نیست.

کد 307 Temporary Redirect

Redirect موقت است و Method و Body اصلی باید حفظ شوند.

کد 308 Permanent Redirect

Redirect دائمی است و Method و Body اصلی باید حفظ شوند.

کد 400 Bad Request

Request از نظر Syntax، داده یا قرارداد عمومی نامعتبر است:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request body is invalid."
  }
}

علت‌های احتمالی:

JSON نامعتبر
فیلد الزامی حذف شده
نوع داده اشتباه
پارامتر نامعتبر
Body ناقص

کد 401 Unauthorized

معمولاً یعنی احراز هویت انجام نشده یا Credential معتبر نیست.

علت‌های احتمالی:

API Key ارسال نشده
Token منقضی شده
API Key اشتباه است
فرمت Authorization Header نادرست است

نمونه صحیح Bearer Token:

Authorization: Bearer YOUR_API_KEY

کد 403 Forbidden

Server هویت درخواست‌کننده را می‌شناسد، اما اجازه انجام عملیات را نمی‌دهد.

تفاوت ساده:

401 → ابتدا باید هویت معتبر ارائه شود
403 → هویت یا درخواست شناخته شده، اما مجوز کافی نیست

جزئیات رفتار می‌تواند به طراحی همان API وابسته باشد.

کد 404 Not Found

Resource یا Endpoint پیدا نشده است.

علت‌های رایج:

URL اشتباه
نسخه API اشتباه
شناسه Resource وجود ندارد
Path نادرست
Resource حذف شده است

کد 405 Method Not Allowed

Path وجود دارد، اما Method برای آن مجاز نیست.

برای مثال:

GET /v1/chat/completions

درحالی‌که Endpoint فقط POST را می‌پذیرد.

کد 409 Conflict

Request با وضعیت فعلی Resource تعارض دارد.

نمونه‌ها:

ثبت Email تکراری
تغییر هم‌زمان نسخه Resource
تعارض وضعیت
ایجاد Resource موجود

کد 415 Unsupported Media Type

Server فرمت Body را نمی‌پذیرد.

یکی از علت‌های رایج:

Content-Type: text/plain

درحالی‌که API انتظار دارد:

Content-Type: application/json

کد 422 Unprocessable Content

Syntax درخواست قابل پردازش است، اما داده با قواعد مورد انتظار تطابق ندارد.

برای مثال:

{
  "email": "not-an-email"
}

ممکن است JSON معتبر باشد، اما Validation فیلد Email شکست بخورد.

کد 429 Too Many Requests

Client در بازه مشخص بیش از Limit مجاز درخواست ارسال کرده است.

Server ممکن است Header زیر را برگرداند:

Retry-After: 10

برنامه باید Rate Limit را مدیریت کند و از Retry فوری و بی‌نهایت خودداری کند.

کد 500 Internal Server Error

خطای عمومی داخل Server رخ داده است.

Client معمولاً جزئیات داخلی Server را نمی‌داند. برنامه می‌تواند Request ID و زمان خطا را ثبت کند تا عیب‌یابی آسان‌تر شود.

کد 502 Bad Gateway

یک Gateway یا Proxy از سرویس بالادستی پاسخ معتبر دریافت نکرده است.

کد 503 Service Unavailable

سرویس موقتاً در دسترس نیست؛ برای مثال به دلیل:

نگهداری
بار زیاد
نبود ظرفیت
قطع وابستگی
اختلال موقت

Retry محدود و با Backoff ممکن است مناسب باشد.

کد 504 Gateway Timeout

Gateway در زمان تعیین‌شده از سرویس بالادستی پاسخ دریافت نکرده است.

این خطا با Timeout سمت Client یکسان نیست. در 504 یک Server یا Gateway پاسخ HTTP تولید کرده است، اما در Timeout سمت Client ممکن است اصلاً Response HTTP دریافت نشود.

چرا نباید فقط کد 200 را موفق بدانیم؟

موفقیت می‌تواند با کدهای مختلف نشان داده شود:

200 OK
201 Created
202 Accepted
204 No Content
206 Partial Content

در بسیاری از کتابخانه‌ها این شرط مناسب‌تر است:

if 200 <= response.status_code < 300:
    ...

البته رفتار دقیق باید با قرارداد Endpoint تطبیق داده شود. برای مثال 202 فقط پذیرش پردازش را اعلام می‌کند، نه تکمیل آن.

Header مربوط به Content-Type

فرمت Body ارسال‌شده یا دریافت‌شده را مشخص می‌کند:

Content-Type: application/json

نمونه‌های دیگر:

text/html
text/plain
image/png
application/pdf
multipart/form-data
text/event-stream

فرمت پاسخ قابل قبول برای Client را مشخص می‌کند:

Accept: application/json

تفاوت:

Content-Type → Body فعلی چه فرمتی دارد؟
Accept       → پاسخ را با چه فرمتی می‌خواهم؟

اطلاعات احراز هویت را ارسال می‌کند:

Authorization: Bearer YOUR_DARVAREH_API_KEY

API Key واقعی را در Browser، Repository عمومی، Log یا پیام خطا نمایش ندهید.

اطلاعاتی درباره Client ارسال‌کننده درخواست ارائه می‌دهد:

User-Agent: darvareh-example-client/1.0

بعضی سرویس‌ها از User-Agent برای آمار، سازگاری یا عیب‌یابی استفاده می‌کنند.

Header مربوط به Content-Length

اندازه Body را بر حسب Byte مشخص می‌کند:

Content-Length: 125

کتابخانه‌های HTTP معمولاً این مقدار را خودکار تنظیم می‌کنند. آن را دستی و با مقدار اشتباه ارسال نکنید.

رفتار Cache را کنترل می‌کند:

Cache-Control: no-cache

یا:

Cache-Control: public, max-age=3600

مفهوم دقیق Directiveهای Cache با نام ظاهری آن‌ها همیشه یکسان نیست؛ برای پیاده‌سازی جدی باید مستندات Caching بررسی شود.

در Redirect یا ایجاد Resource کاربرد دارد:

Location: /users/126

زمان پیشنهادی صبر پیش از درخواست بعدی را اعلام می‌کند:

Retry-After: 30

مقدار می‌تواند مدت‌زمان یا تاریخ باشد.

بعضی APIها شناسه‌ای برای پیگیری درخواست ارائه می‌دهند:

X-Request-ID: req_123456

نام دقیق این Header استاندارد واحدی در همه سرویس‌ها ندارد. در زمان گزارش خطا، Request ID می‌تواند برای پشتیبانی و بررسی Log مفید باشد.

تفاوت HTTP و HTTPS

HTTPS همان ارتباط HTTP روی یک لایه رمزنگاری‌شده TLS است.

در HTTP معمولی، داده در مسیر انتقال محافظت TLS ندارد. HTTPS اهداف مهمی مانند این موارد را فراهم می‌کند:

رمزنگاری ارتباط
کاهش امکان مشاهده محتوای در حال انتقال
بررسی هویت Server از طریق Certificate
تشخیص تغییر داده در مسیر

برای APIهایی که Credential، API Key یا اطلاعات کاربر جابه‌جا می‌کنند باید از HTTPS استفاده شود.

نمونه Base URL درواره:

https://api.darvareh.ir/v1

استفاده از HTTPS به‌تنهایی تمام مسائل ایمنی برنامه را حل نمی‌کند. مدیریت Secret، دسترسی‌ها، Validation و Log همچنان ضروری است.

HTTP/1.1 چیست؟

HTTP/1.1 نسخه‌ای بسیار پرکاربرد از HTTP است که مفاهیمی مانند اتصال پایدار و Headerهای متنی را ارائه می‌دهد.

در این نسخه، پیام‌ها در توضیح مفهومی شبیه نمونه زیر هستند:

GET /v1/models HTTP/1.1
Host: api.example.com
Accept: application/json

اتصال می‌تواند برای چند Request دوباره استفاده شود، اما مدیریت چند درخواست هم‌زمان روی یک اتصال نسبت به نسخه‌های جدید محدودتر است.

HTTP/2 چیست؟

HTTP/2 معنای اصلی Method، Status Code و Header را حفظ می‌کند، اما انتقال پیام‌ها را با Frameهای Binary انجام می‌دهد.

ویژگی‌های مهم:

Multiplexing چند Stream روی یک اتصال
فشرده‌سازی Headerها
استفاده بهتر از اتصال
کاهش بعضی محدودیت‌های HTTP/1.1

برنامه معمولاً همچنان با همان مفاهیم Request و Response کار می‌کند و کتابخانه HTTP جزئیات Frameها را مدیریت می‌کند.

HTTP/3 چیست؟

HTTP/3 از QUIC استفاده می‌کند که روی UDP ساخته شده است.

اهداف اصلی آن شامل کاهش تأخیر اتصال و بهبود رفتار در شبکه‌های متغیر است. منطق سطح Application مانند Method، Header و Status Code همچنان برای توسعه‌دهنده آشنا باقی می‌ماند.

نوع نسخه HTTP معمولاً نباید بدون نیاز مشخص وارد Business Logic برنامه شود.

Keep-Alive و Connection Reuse

ساخت اتصال جدید برای هر Request هزینه دارد. کتابخانه‌ها و Clientها معمولاً تلاش می‌کنند اتصال را دوباره استفاده کنند.

در Python، requests.Session امکان Connection Reuse را فراهم می‌کند:

import requests


with requests.Session() as session:
    response_one = session.get(
        "https://api.example.com/v1/items",
        timeout=30,
    )

    response_two = session.get(
        "https://api.example.com/v1/users",
        timeout=30,
    )

در برنامه پرترافیک، انتخاب Client مناسب، Connection Pool و محدودیت هم‌زمانی اهمیت دارد.

Timeout چیست؟

Timeout حداکثر زمانی است که Client برای یک مرحله از عملیات منتظر می‌ماند.

اگر Timeout تعیین نکنید، یک درخواست ممکن است مدت نامحدودی منتظر بماند و Worker یا برنامه را اشغال کند.

در Python:

response = requests.get(
    "https://api.example.com/v1/items",
    timeout=30,
)

برای تعیین جداگانه Connect Timeout و Read Timeout:

response = requests.get(
    "https://api.example.com/v1/items",
    timeout=(10, 60),
)

در این مثال:

حداکثر زمان برقراری اتصال ۱۰ ثانیه است.
Read Timeout برابر ۶۰ ثانیه است.

Read Timeout الزاماً سقف کل زمان Request نیست؛ معنای دقیق آن به کتابخانه و فاصله دریافت داده وابسته است.

انواع خطاهای ارتباطی

DNS Error

نام دامنه به IP تبدیل نمی‌شود.

Connection Error

اتصال به Server برقرار نمی‌شود.

Connect Timeout

اتصال در زمان مشخص برقرار نشده است.

Read Timeout

اتصال برقرار شده، اما داده در زمان مورد انتظار دریافت نشده است.

HTTP Error

Server یک Response با Status Code خطا مانند 400 یا 500 برگردانده است.

Parse Error

Response دریافت شده، اما Body با فرمت مورد انتظار قابل Parse نیست.

این خطاها را یکسان مدیریت نکنید. برای مثال، 400 معمولاً با Retry خودکار حل نمی‌شود، اما 503 ممکن است موقت باشد.

Retry چیست؟

Retry یعنی ارسال مجدد Request پس از شکست.

Retry برای بعضی خطاهای موقت مفید است:

خطای اتصال موقت
429 Too Many Requests
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

اما Retry باید محدود باشد و فاصله زمانی آن افزایش پیدا کند.

نمونه Backoff:

Retry 1 → 1 second
Retry 2 → 2 seconds
Retry 3 → 4 seconds

برای جلوگیری از ارسال هم‌زمان تعداد زیادی Retry می‌توان مقدار تصادفی کوچکی یا Jitter اضافه کرد.

چرا نباید همه Requestها را Retry کنیم؟

اگر یک POST عملیات مالی یا ایجاد Resource را انجام دهد، ارسال مجدد ممکن است عملیات را تکرار کند.

پیش از Retry بررسی کنید:

Method چیست؟
عملیات Idempotent است؟
Server درخواست اول را پردازش کرده است؟
API از Idempotency Key پشتیبانی می‌کند؟
خطا موقت است یا دائمی؟
Retry-After وجود دارد؟
تعداد Retry محدود است؟

برای خطاهای زیر معمولاً Retry فوری مناسب نیست:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
415 Unsupported Media Type
422 Unprocessable Content

ابتدا Request یا Credential باید اصلاح شود.

Rate Limit چیست؟

Rate Limit تعداد Request مجاز در یک بازه زمانی را محدود می‌کند.

محدودیت ممکن است بر اساس این موارد باشد:

API Key
کاربر
IP
Endpoint
مدل
حساب
تعداد Token
زمان

وقتی Limit رد شود، API ممکن است 429 برگرداند.

راهکارهای مناسب:

کاهش Concurrency
Queue کردن درخواست‌ها
رعایت Retry-After
Exponential Backoff
Cache کردن نتیجه‌های قابل استفاده مجدد
Batch کردن عملیات در صورت پشتیبانی
محدودکردن Requestهای تکراری
پایش مصرف

Streaming در HTTP

در پاسخ معمولی، Client منتظر می‌ماند تا Body کامل شود:

Request
  ↓
Processing
  ↓
Complete Response

در Streaming، Server داده را به‌تدریج ارسال می‌کند:

Request
  ↓
Chunk 1
Chunk 2
Chunk 3
...
Done

برای مدل‌های زبانی، Streaming باعث می‌شود کاربر بخش‌های اولیه پاسخ را زودتر ببیند.

یکی از فرمت‌های رایج:

Content-Type: text/event-stream

نمونه ساده Event:

data: {"content":"سلام"}

data: {"content":"، چطور"}

data: {"content":" کمکتان کنم؟"}

هر Chunk الزاماً یک پاسخ JSON کامل نهایی نیست. Client باید Protocol مربوط به Stream را رعایت و داده‌ها را به ترتیب پردازش کند.

Streaming معمولاً زمان تولید مدل یا تعداد Token را کم نمی‌کند؛ بیشتر نحوه تحویل پاسخ را تغییر می‌دهد.

ارسال Request با cURL

دریافت Header و Body پاسخ:

curl \
  --include \
  https://api.example.com/v1/items

ارسال POST JSON:

curl \
  --request POST \
  --url https://api.example.com/v1/items \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "name": "Example",
    "active": true
  }'

نمایش جزئیات بیشتر ارتباط:

curl --verbose https://api.example.com/v1/items

خروجی Verbose ممکن است Headerهای حساس را نمایش دهد. پیش از ارسال Log برای دیگران، Authorization، Cookie و Tokenها را حذف کنید.

اتصال به API درواره با cURL

curl \
  --request POST \
  --url https://api.darvareh.ir/v1/chat/completions \
  --header "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "system",
        "content": "پاسخ را دقیق و فارسی ارائه کن."
      },
      {
        "role": "user",
        "content": "تفاوت HTTP Request و Response چیست؟"
      }
    ],
    "temperature": 0.2
  }'

برای دریافت API Key در درواره ثبت‌نام کنید. Model ID مناسب و قیمت به‌روز را از صفحه مدل‌های درواره بردارید.

ارسال Request با Python

نصب کتابخانه‌ها:

python -m pip install requests python-dotenv

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID

کد:

import os
from time import perf_counter

import requests
from dotenv import load_dotenv


load_dotenv()

api_key = os.getenv("DARVAREH_API_KEY")
model_id = os.getenv("DARVAREH_MODEL_ID")

if not api_key:
    raise RuntimeError(
        "DARVAREH_API_KEY is not configured."
    )

if not model_id:
    raise RuntimeError(
        "DARVAREH_MODEL_ID is not configured."
    )

url = (
    "https://api.darvareh.ir/v1"
    "/chat/completions"
)

payload = {
    "model": model_id,
    "messages": [
        {
            "role": "system",
            "content": (
                "پاسخ را دقیق و به زبان فارسی "
                "ارائه کن."
            ),
        },
        {
            "role": "user",
            "content": (
                "HTTP Status Code را توضیح بده."
            ),
        },
    ],
    "temperature": 0.2,
}

started_at = perf_counter()

try:
    response = requests.post(
        url,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
            "User-Agent": (
                "darvareh-http-tutorial/1.0"
            ),
        },
        json=payload,
        timeout=(10, 60),
    )
except requests.ConnectTimeout as error:
    raise RuntimeError(
        "Connection to the API timed out."
    ) from error
except requests.ReadTimeout as error:
    raise RuntimeError(
        "The API response timed out."
    ) from error
except requests.ConnectionError as error:
    raise RuntimeError(
        "Could not connect to the API."
    ) from error

elapsed_seconds = perf_counter() - started_at

request_id = (
    response.headers.get("X-Request-ID")
    or response.headers.get("Request-ID")
)

print(f"Status: {response.status_code}")
print(f"Elapsed: {elapsed_seconds:.2f} seconds")

if request_id:
    print(f"Request ID: {request_id}")

try:
    response.raise_for_status()
except requests.HTTPError as error:
    content_type = response.headers.get(
        "Content-Type",
        "",
    )

    preview = response.text[:500]

    raise RuntimeError(
        f"HTTP {response.status_code}, "
        f"Content-Type={content_type}, "
        f"Body={preview}"
    ) from error

content_type = response.headers.get(
    "Content-Type",
    "",
).lower()

if "application/json" not in content_type:
    raise RuntimeError(
        "Expected a JSON response but received "
        f"{content_type or 'unknown'}."
    )

try:
    result = response.json()
except requests.JSONDecodeError as error:
    raise RuntimeError(
        "Response body is not valid JSON."
    ) from error

try:
    answer = (
        result["choices"][0]["message"]["content"]
    )
except (KeyError, IndexError, TypeError) as error:
    raise RuntimeError(
        "Unexpected API response structure."
    ) from error

print(answer)

در پیام خطا نباید API Key یا Authorization Header را چاپ کنید.

استفاده از Session در Python

برای چند Request متوالی:

import requests


with requests.Session() as session:
    session.headers.update(
        {
            "Authorization": (
                "Bearer YOUR_DARVAREH_API_KEY"
            ),
            "Accept": "application/json",
            "User-Agent": (
                "darvareh-python-client/1.0"
            ),
        }
    )

    response = session.get(
        "https://api.darvareh.ir/v1/models",
        timeout=(10, 30),
    )

    response.raise_for_status()

    data = response.json()

API Key را در برنامه واقعی از Environment Variable بخوانید، نه از String ثابت.

ارسال Request با JavaScript

در Backend مبتنی بر Node.js:

const apiKey = process.env.DARVAREH_API_KEY;
const modelId = process.env.DARVAREH_MODEL_ID;

if (!apiKey || !modelId) {
  throw new Error(
    "API configuration is incomplete",
  );
}

const controller = new AbortController();

const timeoutId = setTimeout(
  () => controller.abort(),
  60_000,
);

try {
  const response = await fetch(
    "https://api.darvareh.ir/v1/chat/completions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        model: modelId,
        messages: [
          {
            role: "user",
            content: "HTTP چیست؟",
          },
        ],
        temperature: 0.2,
      }),
      signal: controller.signal,
    },
  );

  const responseText = await response.text();

  if (!response.ok) {
    throw new Error(
      `HTTP ${response.status}: ` +
        responseText.slice(0, 500),
    );
  }

  let result;

  try {
    result = JSON.parse(responseText);
  } catch {
    throw new Error(
      "Response body is not valid JSON",
    );
  }

  const answer =
    result?.choices?.[0]?.message?.content;

  if (typeof answer !== "string") {
    throw new Error(
      "Unexpected response structure",
    );
  }

  console.log(answer);
} finally {
  clearTimeout(timeoutId);
}

Fetch در بسیاری از پیاده‌سازی‌ها برای Status Codeهایی مانند 404 یا 500 به‌تنهایی Promise را Reject نمی‌کند. باید response.ok یا response.status را صریح بررسی کنید.

API Key را در کد JavaScript قابل اجرا در Browser قرار ندهید. Browser باید به Backend خودتان متصل شود و Backend درخواست را به API درواره ارسال کند.

پروژه عملی: ساخت HTTP Client قابل عیب‌یابی برای API هوش مصنوعی

در این پروژه یک Client کوچک می‌سازیم که:

API Key را از Environment می‌خواند.
Request را با Timeout ارسال می‌کند.
Status Code را بررسی می‌کند.
Content-Type را اعتبارسنجی می‌کند.
زمان پاسخ را اندازه می‌گیرد.
Request ID را در صورت وجود ثبت می‌کند.
پاسخ JSON را Parse می‌کند.
خطاهای شبکه و HTTP را تفکیک می‌کند.
اطلاعات حساس را Log نمی‌کند.

ساختار پروژه

http-ai-client/
├── .env
├── .gitignore
├── requirements.txt
├── client.py
└── main.py

فایل requirements.txt

requests>=2.32,<3
python-dotenv>=1.0,<2

نصب:

python -m pip install -r requirements.txt

فایل .gitignore

.env
.venv/
__pycache__/
*.pyc

فایل client.py

from dataclasses import dataclass
from time import perf_counter
from typing import Any

import requests


@dataclass(frozen=True)
class HTTPResult:
    status_code: int
    elapsed_seconds: float
    request_id: str | None
    data: dict[str, Any]


class APIClientError(RuntimeError):
    pass


class DarvarehHTTPClient:
    def __init__(
        self,
        api_key: str,
        model_id: str,
        base_url: str = (
            "https://api.darvareh.ir/v1"
        ),
    ) -> None:
        if not api_key.strip():
            raise ValueError(
                "api_key cannot be empty."
            )

        if not model_id.strip():
            raise ValueError(
                "model_id cannot be empty."
            )

        self.model_id = model_id
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()

        self.session.headers.update(
            {
                "Authorization": (
                    f"Bearer {api_key}"
                ),
                "Content-Type": "application/json",
                "Accept": "application/json",
                "User-Agent": (
                    "darvareh-http-client/1.0"
                ),
            }
        )

    def close(self) -> None:
        self.session.close()

    def chat(
        self,
        prompt: str,
    ) -> HTTPResult:
        cleaned_prompt = prompt.strip()

        if not cleaned_prompt:
            raise ValueError(
                "prompt cannot be empty."
            )

        payload = {
            "model": self.model_id,
            "messages": [
                {
                    "role": "system",
                    "content": (
                        "پاسخ را دقیق و فارسی "
                        "ارائه کن."
                    ),
                },
                {
                    "role": "user",
                    "content": cleaned_prompt,
                },
            ],
            "temperature": 0.2,
        }

        started_at = perf_counter()

        try:
            response = self.session.post(
                f"{self.base_url}/chat/completions",
                json=payload,
                timeout=(10, 60),
            )
        except requests.ConnectTimeout as error:
            raise APIClientError(
                "Connect timeout."
            ) from error
        except requests.ReadTimeout as error:
            raise APIClientError(
                "Read timeout."
            ) from error
        except requests.ConnectionError as error:
            raise APIClientError(
                "Connection failed."
            ) from error
        except requests.RequestException as error:
            raise APIClientError(
                "Unexpected request error."
            ) from error

        elapsed_seconds = (
            perf_counter() - started_at
        )

        request_id = (
            response.headers.get("X-Request-ID")
            or response.headers.get("Request-ID")
        )

        if not 200 <= response.status_code < 300:
            preview = response.text[:500]

            raise APIClientError(
                f"HTTP {response.status_code}; "
                f"request_id={request_id}; "
                f"body={preview}"
            )

        content_type = response.headers.get(
            "Content-Type",
            "",
        ).lower()

        if "application/json" not in content_type:
            raise APIClientError(
                "Expected application/json, "
                f"received {content_type or 'unknown'}."
            )

        try:
            data = response.json()
        except requests.JSONDecodeError as error:
            raise APIClientError(
                "Invalid JSON response."
            ) from error

        if not isinstance(data, dict):
            raise APIClientError(
                "Response root must be an object."
            )

        return HTTPResult(
            status_code=response.status_code,
            elapsed_seconds=elapsed_seconds,
            request_id=request_id,
            data=data,
        )

    def __enter__(
        self,
    ) -> "DarvarehHTTPClient":
        return self

    def __exit__(
        self,
        exc_type: object,
        exc_value: object,
        traceback: object,
    ) -> None:
        self.close()

فایل main.py

import os

from dotenv import load_dotenv

from client import (
    APIClientError,
    DarvarehHTTPClient,
)


def main() -> None:
    load_dotenv()

    api_key = os.getenv(
        "DARVAREH_API_KEY",
        "",
    )

    model_id = os.getenv(
        "DARVAREH_MODEL_ID",
        "",
    )

    if not api_key:
        raise RuntimeError(
            "DARVAREH_API_KEY is missing."
        )

    if not model_id:
        raise RuntimeError(
            "DARVAREH_MODEL_ID is missing."
        )

    try:
        with DarvarehHTTPClient(
            api_key=api_key,
            model_id=model_id,
        ) as client:
            result = client.chat(
                "تفاوت HTTP و HTTPS چیست؟"
            )
    except (
        ValueError,
        APIClientError,
    ) as error:
        print(f"Request failed: {error}")
        return

    print(
        f"Status: {result.status_code}"
    )

    print(
        "Elapsed: "
        f"{result.elapsed_seconds:.2f}s"
    )

    if result.request_id:
        print(
            f"Request ID: {result.request_id}"
        )

    try:
        answer = (
            result.data["choices"][0]
            ["message"]["content"]
        )
    except (
        KeyError,
        IndexError,
        TypeError,
    ):
        print(
            "Unexpected response structure."
        )
        return

    print(f"\n{answer}")


if __name__ == "__main__":
    main()

اجرای پروژه

python main.py

این Client برای آموزش طراحی شده است. در پروژه Production باید مواردی مانند Observability، Retry Policy، Concurrency، Budget Control و قرارداد دقیق پاسخ نیز متناسب با معماری سیستم پیاده‌سازی شوند.

عیب‌یابی مرحله‌ای HTTP Request

وقتی API کار نمی‌کند، این ترتیب را بررسی کنید:

۱. URL

Scheme صحیح است؟
Host درست است؟
نسخه API صحیح است؟
Path درست است؟

۲. Method

GET یا POST؟
Endpoint این Method را پشتیبانی می‌کند؟

۳. Header

Authorization ارسال شده؟
Bearer نوشته شده؟
Content-Type صحیح است؟
Accept مناسب است؟

۴. Body

JSON معتبر است؟
فیلدهای Required وجود دارند؟
نوع داده درست است؟
Model ID صحیح است؟

۵. Status Code

400 → Request
401 → Credential
403 → Permission
404 → URL یا Resource
405 → Method
415 → Content-Type
422 → Validation
429 → Rate Limit
5xx → Server یا Upstream

۶. Response Header

Content-Type چیست؟
Request ID وجود دارد؟
Retry-After وجود دارد؟
Location وجود دارد؟

۷. Response Body

Body خطا را بخوانید، اما پیش از ثبت یا اشتراک‌گذاری، اطلاعات حساس را حذف کنید.

۸. Timeout و شبکه

تفاوت DNS، Connection، Connect Timeout، Read Timeout و HTTP Error را مشخص کنید.

اشتباهات رایج هنگام کار با HTTP

فرض اینکه هر Response دارای JSON است

ممکن است Body متن، HTML، فایل یا خالی باشد.

Parse کردن پاسخ 204

204 No Content Body ندارد.

بررسی‌نکردن response.ok در Fetch

Fetch می‌تواند Response با 500 برگرداند بدون اینکه صرفاً به دلیل Status Code Reject شود.

نداشتن Timeout

Request ممکن است Worker را برای مدت طولانی اشغال کند.

Retry بی‌نهایت

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

قرار‌دادن API Key در Frontend

هر چیزی که به Browser ارسال شود می‌تواند توسط کاربر مشاهده شود.

استفاده از GET برای عملیات تغییردهنده

باعث رفتار غیرقابل پیش‌بینی Cache، Crawler و Client می‌شود.

فرض اینکه POST همیشه Resource می‌سازد

POST می‌تواند عملیات مختلفی را شروع کند. قرارداد Endpoint تعیین‌کننده است.

یکی‌دانستن 401 و 403

این دو کد معنای متفاوتی دارند و عیب‌یابی آن‌ها نیز متفاوت است.

نمایش Log کامل Request

Log ممکن است Authorization، Cookie، داده شخصی یا Prompt محرمانه داشته باشد.

ارسال دوباره POST بدون بررسی

درخواست اول ممکن است در Server انجام شده باشد، حتی اگر Client پاسخ را دریافت نکرده باشد.

بهترین روش‌های کار با HTTP API

Base URL را در Configuration نگه دارید.
API Key را از Environment بخوانید.
برای تمام Requestها Timeout تعیین کنید.
Status Code را پیش از Parse بررسی کنید.
Content-Type را اعتبارسنجی کنید.
Error Body را محدود و پاک‌سازی‌شده Log کنید.
Request ID را برای عیب‌یابی نگه دارید.
Retry را فقط برای خطاهای مناسب انجام دهید.
برای Retry از Backoff و Jitter استفاده کنید.
Idempotency عملیات را بررسی کنید.
Rate Limit را مدیریت کنید.
ارتباط را با Session یا Client Pool دوباره استفاده کنید.
داده ورودی و خروجی را Validate کنید.
منطق برنامه را به متن Reason Phrase وابسته نکنید.
قابلیت‌های Streaming را جداگانه پیاده‌سازی کنید.
Model ID را از کد اصلی جدا نگه دارید.
مصرف و زمان پاسخ API را پایش کنید.

چک‌لیست اتصال به API هوش مصنوعی

پیش از استقرار بررسی کنید:

Base URL صحیح است.
Endpoint صحیح انتخاب شده است.
Method درست است.
HTTPS استفاده می‌شود.
API Key در Backend نگهداری می‌شود.
Authorization Header درست است.
Content-Type روی application/json قرار دارد.
JSON معتبر است.
Model ID از منبع به‌روز گرفته شده است.
Connect Timeout وجود دارد.
Read Timeout وجود دارد.
خطاهای 4xx مدیریت می‌شوند.
خطاهای 5xx مدیریت می‌شوند.
429 و Retry-After بررسی می‌شوند.
Retry محدود است.
پاسخ پیش از استفاده Validate می‌شود.
Stream به‌صورت Incremental پردازش می‌شود.
Logها Secret ندارند.
Request ID ثبت می‌شود.
مصرف Token و هزینه پایش می‌شود.

پرسش‌های متداول

HTTP مخفف چیست؟

HTTP مخفف Hypertext Transfer Protocol است.

HTTP چه کاری انجام می‌دهد؟

قواعد تبادل Request و Response میان Client و Server را تعریف می‌کند.

تفاوت HTTP و HTTPS چیست؟

HTTPS ارتباط HTTP را روی TLS منتقل می‌کند و از رمزنگاری، بررسی هویت Server و تمامیت داده در مسیر پشتیبانی می‌کند.

HTTP Request چیست؟

پیامی است که Client برای درخواست Resource یا اجرای عملیات به Server می‌فرستد. Request شامل Method، مقصد، Headerها و گاهی Body است.

HTTP Response چیست؟

پاسخ Server به Request است و شامل Status Code، Headerها و Body اختیاری می‌شود.

تفاوت GET و POST چیست؟

GET برای دریافت Resource و POST معمولاً برای ارسال داده، ایجاد Resource یا شروع عملیات استفاده می‌شود. قرارداد دقیق هر Endpoint باید مستند باشد.

تفاوت PUT و PATCH چیست؟

PUT معمولاً برای جایگزینی کامل Resource و PATCH برای تغییر بخشی از آن استفاده می‌شود. رفتار دقیق به قرارداد API وابسته است.

Status Code 401 چیست؟

معمولاً نشان می‌دهد Credential معتبر ارائه نشده یا احراز هویت موفق نبوده است.

Status Code 403 چیست؟

Server درخواست را می‌شناسد، اما اجازه انجام عملیات را نمی‌دهد.

Status Code 429 چیست؟

تعداد درخواست‌ها از Rate Limit مجاز عبور کرده است. Client باید سرعت ارسال را کاهش دهد و در صورت وجود Retry-After آن را رعایت کند.

Status Code 500 چیست؟

یک خطای عمومی در Server رخ داده است. برای گزارش مشکل، زمان، Endpoint و Request ID را ثبت کنید؛ اما Secretها را ارسال نکنید.

آیا HTTP همیشه JSON منتقل می‌کند؟

خیر. HTTP می‌تواند HTML، متن، JSON، XML، تصویر، صوت، ویدئو، PDF و داده Binary را منتقل کند.

Content-Type چه تفاوتی با Accept دارد؟

Content-Type فرمت Body فعلی و Accept فرمت پاسخ مورد انتظار را اعلام می‌کند.

آیا Streaming همان WebSocket است؟

خیر. HTTP Streaming، Server-Sent Events و WebSocket روش‌های متفاوتی هستند. بعضی APIهای مدل زبانی پاسخ را با SSE روی HTTP ارسال می‌کنند.

Base URL درواره چیست؟

https://api.darvareh.ir/v1

Endpoint چت درواره چیست؟

POST https://api.darvareh.ir/v1/chat/completions

Model ID درواره را از کجا دریافت کنیم؟

Model ID و قیمت به‌روز مدل‌ها در صفحه مدل‌های درواره قرار دارد.

جمع‌بندی

HTTP پایه ارتباط در وب و بسیاری از APIها است. Client یک Request شامل Method، URL، Header و Body اختیاری ارسال می‌کند و Server یک Response شامل Status Code، Header و Body برمی‌گرداند.

برای کار حرفه‌ای با HTTP باید این مفاهیم را به‌درستی از یکدیگر جدا کنید:

URL و Endpoint
Method و عملیات
Header و Body
Status Code و خطای شبکه
Content-Type و Accept
Connect Timeout و Read Timeout
Retry و Idempotency
پاسخ معمولی و Streaming
HTTP و HTTPS
JSON معتبر و داده معتبر

ارسال یک Request موفق فقط آغاز کار است. یک Client قابل اتکا باید Timeout، خطا، Rate Limit، Parse، Validation، Request ID و مصرف منابع را نیز مدیریت کند.

برای آزمایش HTTP با یک API واقعی می‌توانید در درواره ثبت‌نام کرده، API Key بسازید و با Base URL زیر به مدل‌های مختلف هوش مصنوعی متصل شوید:

https://api.darvareh.ir/v1

برای مشاهده Model IDها، قابلیت‌ها و قیمت‌های به‌روز، صفحه مدل‌ها و قیمت‌های درواره را ببینید.

منابع رسمی

مقالات مرتبط

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.

پاسخ کوتاه: HTTP چیست؟

پروتکل چیست؟

Client چیست؟

Server چیست؟

مدل Request و Response

HTTP Stateless است یعنی چه؟

URL چیست؟

Scheme

Host

Port

Path

Query String

Fragment

Endpoint چیست؟

ساختار HTTP Request

Request Line

HTTP Header چیست؟

HTTP Body چیست؟

ساختار HTTP Response

Status Line

HTTP Method چیست؟

متد GET

متد POST

متد PUT

متد PATCH

متد DELETE

متد HEAD

متد OPTIONS

Safe Method چیست؟

Idempotent Method چیست؟

مهم‌ترین HTTP Status Codeها

کد 200 OK

کد 201 Created

کد 202 Accepted

کد 204 No Content

کد 301 Moved Permanently

کد 302 Found

کد 304 Not Modified

کد 307 Temporary Redirect

کد 308 Permanent Redirect

کد 400 Bad Request

کد 401 Unauthorized

کد 403 Forbidden

کد 404 Not Found

کد 405 Method Not Allowed

کد 409 Conflict

کد 415 Unsupported Media Type

کد 422 Unprocessable Content

کد 429 Too Many Requests

کد 500 Internal Server Error

کد 502 Bad Gateway

کد 503 Service Unavailable

کد 504 Gateway Timeout

چرا نباید فقط کد 200 را موفق بدانیم؟

Headerهای مهم HTTP

Header مربوط به Content-Type

Header مربوط به Accept

Header مربوط به Authorization

Header مربوط به User-Agent

Header مربوط به Content-Length

Header مربوط به Cache-Control

Header مربوط به Location

Header مربوط به Retry-After

Header مربوط به Request ID

تفاوت HTTP و HTTPS

HTTP/1.1 چیست؟

HTTP/2 چیست؟

HTTP/3 چیست؟

Keep-Alive و Connection Reuse

Timeout چیست؟

انواع خطاهای ارتباطی

DNS Error

Connection Error

Connect Timeout

Read Timeout

HTTP Error

Parse Error

Retry چیست؟

چرا نباید همه Requestها را Retry کنیم؟

Rate Limit چیست؟