Httpie: چیست، کلاینت HTTP برای خط فرمان

Httpie چیست و چه تفاوتی با cURL دارد

Httpie (یا HTTPie) یک ابزار کنسولی نوشتهشده به زبان Python است که ارسال درخواستهای HTTP را در مقایسه با cURL سادهتر میکند. تفاوت اصلی سینتکسی نزدیک به زبان طبیعی است: آرگومانها با فاصله جدا میشوند، هدرها با دونقطه و دادههای JSON با علامت مساوی، بدون نیاز به escape کردن نقلقولها مشخص میشوند.

مقایسه cURL و Httpie

همان درخواست POST در cURL به حداقل سه فلگ (-X, -H, -d) و escape کردن دستی JSON نیاز دارد. Httpie همین کار را با سه کلمه بدون فلگ انجام میدهد، بهطور خودکار Content-Type: application/json را تنظیم میکند و خروجی را رنگی میکند. پاسخ بهصورت پیشفرض با فاصلهگذاری و هایلایت سینتکس قالببندی میشود.

سینتکس درخواستها در Httpie

Httpie از یک فرمت واحد خط فرمان بدون فلگ برای پارامترهای اصلی استفاده میکند. متد HTTP بهعنوان اولین آرگومان (GET, POST, PUT, DELETE, PATCH) و URL بهعنوان دومین مشخص میشود. اگر متد حذف شود، Httpie بهطور خودکار GET (برای درخواستهای بدون بدنه) یا POST (با بدنه) را انتخاب میکند.

انواع آرگومانها

• Header:Value — هدرهای درخواست با دونقطه، بدون فاصله بعد از دونقطه: Authorization:"Bearer token".
• key=value — فیلدهای شیء JSON در بدنه درخواست: name=John age=30.
• key:=value — مقادیر JSON غیررشتهای (اعداد، مقادیر بولین، آرایهها): active:=true tags:=["dev","test"].
• key@file — بارگذاری مقدار از فایل: avatar@~/photo.jpg.

Httpie بهطور خودکار نوع داده را تشخیص میدهد: اگر key=value ارسال شود، بدنه بهصورت JSON ارسال میشود. اگر متن خام از طریق --raw ارسال شود — بهصورت متن ساده. فرمت form-data با فلگ -f فعال میشود.

# درخواست POST با دادههای JSON و هدر
http POST https://api.example.com/users \
    name="John Doe" \
    email="john@example.com" \
    role:="admin" \
    Authorization:"Bearer test123"

# پاسخ با هایلایت و Pretty-print
HTTP/1.1 201 Created
Content-Type: application/json
{
    "id": 42,
    "name": "John Doe"
}

کار با JSON و فایلها

سریالسازی JSON در Httpie بهطور خودکار کار میکند: مقداری که بهصورت key=value ارسال میشود به فیلد رشتهای JSON تبدیل میشود. برای اعداد و مقادیر بولین از key:=value استفاده میشود. اشیاء تودرتو با نماد نقطهای ساخته میشوند: address.city=Moscow.

بارگذاری فایلها و دادههای باینری

Httpie از فرمت multipart/form-data برای بارگذاری فایلها و دادهها از طریق سینتکس key@path پشتیبانی میکند. اگر لازم است محتوای یک فایل بهعنوان بدنه خام درخواست ارسال شود، از بازنویسی ورودی استفاده میشود: http POST example.com < file.json. برای دانلود پاسخ در یک فایل از فلگ -d (download) استفاده میشود.

# ارسال JSON از فایل
http POST https://api.example.com/users < user.json

# بارگذاری فایل از طریق multipart
http -f POST https://api.example.com/upload \
    photo@~/photo.jpg \
    description="Profile photo"

مدیریت نشستها و کوکیها

نشستها در Httpie وضعیت را بین درخواستها ذخیره میکنند: کوکیها، هدرها و پارامترهای احراز هویت. نشست با فلگ --session=name ایجاد میشود. دادههای نشست در فایل JSON در پوشه ~/.httpie/sessions/ ذخیره میشوند. نشست با پسوند :readonly بعد از درخواست بهروزرسانی نمیشود.

نمونه تست نشست

ابتدا یک POST به /auth/login با دادههای ورود ارسال میشود — سرور کوکی نشست را برمیگرداند. همه درخواستهای بعدی به نقاط پایانی محافظتشده در همان نشست بهطور خودکار کوکی ذخیرهشده را ارسال میکنند که رفتار مرورگر را هنگام تست API اپلیکیشن موبایل شبیهسازی میکند.

# مرحله 1: احراز هویت
http --session=app-test POST https://api.example.com/auth/login \
    username="dev" password="secret"

# مرحله 2: درخواست با کوکی نشست ذخیرهشده
http --session=app-test GET https://api.example.com/users/me

احراز هویت و هدرها

Httpie از همه انواع اصلی احراز هویت از طریق فلگها پشتیبانی میکند: -a user:pass برای Basic Auth، --auth-type=digest برای Digest، --auth-type=bearer TOKEN برای Bearer Token. هدرهای سفارشی بهصورت HeaderName:value در هر جای دستور اضافه میشوند.

OAuth 2.0 و Bearer Token

برای تست API با OAuth 2.0، توکن از طریق هدر Authorization منتقل میشود. Httpie چرخه حیات توکن را در سطح هسته مدیریت نمیکند — این کار توسط اسکریپت خارجی انجام میشود. دستور http --auth-type=bearer --auth="$TOKEN" GET https://api.example.com/resource معادل مشخصکردن صریح هدر با توکن است.

استفاده از Httpie در اسکریپتهای CI/CD

Httpie به لطف وابستگیهای صفر (بهجز Python) و خروجی خوانا برای پایپلاینهای CI/CD ایدهآل است. دستورها بدون نیاز به پارس اضافی بهراحتی در لاگها خوانده میشوند. این ابزار از طریق pip نصب میشود و در همه تصاویر محبوب Docker از جمله Alpine، Ubuntu و تصاویر رسمی سیستمهای CI یعنی Jenkins و GitLab در دسترس است. این موضوع Httpie را به انتخاب مناسبی برای تست خودکار REST API و میکروسرویسها تبدیل میکند.

بررسی health-اندارپوینت در دیپلوی

سناریوی معمول — بررسی وضعیت API بعد از دیپلوی اپلیکیشن. Httpie درخواست را به health-اندارپوینت ارسال میکند و اگر پاسخ مطابق انتظار نباشد با کد غیرصفر خاتمه مییابد. فلگ --check-status در صورت کد وضعیت >= 300 بهطور خودکار خطا برمیگرداند.

# Health check در اسکریپت دیپلوی
http --check-status GET https://api.staging.example.com/health
    status:="ok" && \
    echo "API سالم است" || \
    echo "بررسی API ناموفق بود"

امکانات پیشرفته و پلاگینهای Httpie

Httpie از پلاگینها از طریق سیستم Package Index پشتیبانی میکند. پلاگینها انواع جدید احراز هویت، فرمتهای سریالسازی و ترنسپورتها را اضافه میکنند. نصب از طریق pip انجام میشود: pip install httpie-plugin-name. بعد از نصب، پلاگین در راهاندازی بعدی Httpie بهطور خودکار فعال میشود.

پلاگینهای محبوب Httpie

• httpie-jwt-auth — دریافت و بهروزرسانی خودکار توکنهای JWT از طریق مکانیزم refresh token.
• httpie-oauth — پشتیبانی از OAuth 2.0 Client Credentials و جریان Authorization Code با مبادله خودکار کد با توکن.
• httpie-editor — بدنه درخواست را قبل از ارسال در ویرایشگر متن (vim, nano, VS Code) باز میکند.
• httpie-image — تصاویر پاسخ را مستقیماً در ترمینال نمایش میدهد (به kitty یا iTerm2 نیاز دارد).

اسکریپتنویسی و پارس خروجی

Httpie از فیلترکردن مشابه jq از طریق گزینه --pretty=format و خروجی سازگار با cURL از طریق --print پشتیبانی میکند. فلگ --quiet خروجی رنگی را برای خوانایی بهتر در لاگهای CI غیرفعال میکند. برای پردازش برنامهنویسی پاسخ از فلگ --body استفاده کنید که فقط بدنه پاسخ را بدون هدرها نمایش میدهد.

# استخراج فیلد از پاسخ JSON با jq
http GET https://api.example.com/users/1 | jq '.name'

# نمایش فقط بدنه پاسخ (بدون هدرها)
http --body GET https://api.example.com/health

# ارسال دستهای با دادههای مختلف از فایل
while read -r line; do
    http POST https://api.example.com/items $line
done < items.txt

فرمتهای خروجی و سفارشیسازی

Httpie از فرمتهای خروجی از طریق فلگ --print پشتیبانی میکند: H (هدرهای درخواست)، B (بدنه درخواست)، h (هدرهای پاسخ)، b (بدنه پاسخ). ترکیب --print=hb فقط هدرها و بدنه پاسخ را نمایش میدهد. فلگ --pretty=all قالببندی رنگی با فاصلهگذاری را فعال میکند.

طرحهای رنگی سفارشی

Httpie از سفارشیسازی از طریق متغیر HTTPIE_COLORS پشتیبانی میکند. رنگ را برای URL، هدرها، JSON و کدهای وضعیت تنظیم کنید. تمهای داخلی موجود است: autumn, borland, fruity, monokai, native, tango برای ترمینالهای مختلف.

خروجی در فرمت JSON

برای پردازش برنامهنویسی از --body --pretty=none استفاده کنید که JSON خام برمیگرداند. خروجی فشرده برای انتقال به jq، sed و سایر پارسرها در هنگام اتوماسیون تست API در اسکریپتها مفید است.

فرمتهای خروجی و سفارشیسازی ظاهر

Httpie از چندین فرمت خروجی از طریق فلگ --print پشتیبانی میکند: H (هدرهای درخواست)، B (بدنه درخواست)، h (هدرهای پاسخ)، b (بدنه پاسخ). ترکیب --print=hb فقط هدرها و بدنه پاسخ را بهجز متادیتای مربوط به اتصال نمایش میدهد. فلگ --pretty=all قالببندی رنگی با فاصلهگذاری را برای خوانایی فعال میکند.

طرحهای رنگی سفارشی

Httpie از سفارشیسازی رنگها از طریق متغیر محیطی HTTPIE_COLORS پشتیبانی میکند. میتوانید رنگ را برای URL، هدرها، کلیدهای JSON و کدهای وضعیت پاسخ تنظیم کنید. تمهای داخلی موجود است: autumn, borland, fruity, monokai, native و tango برای انواع مختلف ترمینالها و ترجیحات شخصی.

خروجی JSON بدون قالببندی

برای پردازش برنامهنویسی خروجی از ترکیب فلگهای --body --pretty=none استفاده کنید که JSON خام را بدون رنگ و فاصلهگذاری برمیگرداند. خروجی فشرده برای انتقال به jq، sed و سایر پارسرهای کنسولی در هنگام اتوماسیون تست REST API در اسکریپتهای شل مفید است.