REST API: این چیست، روش‌های HTTP و اصل کار در برنامه‌های موبایل

REST API چیست؟

REST API (Representational State Transfer API) — یک سبک معماری است که توسط رای فیلدینگ در سال 2000 در رساله دکترای خود ارائه شد. آن یک مجموعه محدودیت‌ها و اصول برای طراحی پروتکل‌های شبکه تعریف می‌کند. APIی که مطابق این محدودیت‌ها باشد RESTful نامیده می‌شود. REST یک پروتکل یا استاندارد نیست — این یک رویکرد معماری است که از پروتکل‌های موجود (اصلایاً HTTP) برای تبادل داده بین کلینت و سرور استفاده می‌کند.

ایده کلیدی REST — معماری منبع‌محور است. به جای فراخوانی روش‌ها در سرور (مانند SOAP یا RPC)، کلینت با منابع کار می‌کند: لیست آنها را دریافت می‌کند، منابع جدید ایجاد می‌کند، به‌روز می‌کند یا حذف می‌کند. هر منبع یک نهاد در حوزه موردی است: کاربر، سفارش، محصول، مقاله. منبع یک وضعیت دارد که در یک فرمت استاندارد، معمولاً JSON، به کلینت انتقال داده می‌شود. سرور وضعیت کلینت را بین درخواست‌ها ذخیره نمی‌کند — این اصل stateless، یک نیاز کلیدی REST است.

ویژگی‌های اصلی REST API:

• Stateless — هر درخواست از کلینت حاوی تمامی اطلاعات مورد نیاز برای پردازش آن است
• Cacheable — پاسخ‌های سرور باید به صورت صریح به عنوان قابل ذخیره‌سازی یا غیرقابل ذخیره‌سازی علامت‌گذاری شوند
• Layered system — معماری می‌تواند شامل سرورهای واسطه، توزیع‌کننده‌های بار، پروکسی باشد
• Uniform interface — یک رابط واحد از طریق روش‌های HTTP، URL و کدهای وضعیت

اصول معماری REST

REST بر شش محدودیت معماری تدوین‌شده توسط فیلدینگ استوار است. رعایت این محدودیت‌ها قابلیت مقیاس‌پذیری، کارایی و سادگی ادغام را تضمین می‌کند. هر اصل یک مشکل خاص در سیستم‌های توزیع‌شده را حل می‌کند — از نیاز به ذخیره‌سازی تا نیازمندی‌های امنیتی. بیایید هر اصل را به طور مفصل بررسی کنیم.

اصل Uniform Interface به طور افزوده شامل چهار زیرمحدودیت است: شناسایی منابع از طریق URI، دستکاری با منابع از طریق نمایش‌ها، پیام‌های خودتوصیف، و HATEOAS (هایپرمدیا به عنوان موتور وضعیت برنامه). آخرین زیرمحدودیت اغلب در عمل نادیده گرفته می‌شود — اکثر REST API‌های مدرن HATEOAS را به طور کامل پیاده سازی نمی‌کنند و این منجر به بحث‌هایی درباره اینکه آیا چنین APIی «واقعی» RESTful است یا خیر می‌شود.

اصل Stateless یکی از مهم‌ترین ها برای مقیاس‌پذیری است. نبود جلسه در سرور به این معنی است که هر نمونه از سرور می‌تواند هر درخواستی را پردازش کند. این مقیاس‌پذیری افقی را ساده می‌کند: کافی است سرورهای جدید را پشت توزیع‌کننده بار اضافه کنید. برای برنامه‌های موبایل، stateless همچنین به این معنی است که درخواست می‌تواند به هر سرور CDN ارسال شود که برای دسترسی جهانی حیاتی است.

روش‌های HTTP در REST

هر روش HTTP در REST API مربوط به یک عملیات مشخص روی منبع است: GET برای خواندن، POST برای ایجاد، PUT برای به‌روزرسانی کامل، PATCH برای به‌روزرسانی جزئی، DELETE برای حذف. بتوانی بازتاب‌پذیری روش‌ها یک ویژگی کلیدی است: GET، PUT، DELETE بازتاب‌پذیر هستند (اجرای مکرر نتیجه یکسان دارد)، POST و PATCH نیستند. این برای پردازش خطاهای شبکه مهم است زمانی که کلینت نمی‌داند آیا درخواست به سرور رسیده است یا خیر.

• GET — دریافت منبع یا لیست منابع. بازتاب‌پذیر، وضعیت سرور را تغییر نمی‌دهد
• POST — ایجاد منبع جدید. بازتاب‌پذیر نیست، هر بار یک منبع جدید ایجاد می‌کند
• PUT — جایگزینی کامل منبع. بازتاب‌پذیر، اجرای مجدد پس از اولین بار وضعیت را تغییر نمی‌دهد
• PATCH — به‌روزرسانی جزئی منبع. تا حدی بازتاب‌پذیر (بستگی به پیاده‌سازی دارد)
• DELETE — حذف منبع. بازتاب‌پذیر، حذف مجدد 404 برمی‌گرداند نه خطا

کدهای وضعیت HTTP بخش جدایی‌ناپذیر REST API هستند. هر کد معنای مشخصی دارد: 200 OK برای GET موفق، 201 Created برای POST، 204 No Content برای DELETE بدون بدنه پاسخ، 400 Bad Request برای داده‌های نامعتبر، 401 Unauthorized در صورت نبود احراز هویت، 404 Not Found در صورت نبود منبع. استفاده مناسب از کدهای وضعیت API را خودمستند می‌کند و تصحیح خطا را ساده می‌کند.

فرمت‌های داده: JSON و سایر ها

JSON (JavaScript Object Notation) — فرمت اصلی انتقال داده در REST API است. محبوبیت آن به دلیل سادگی، خوانایی برای انسان و پشتیبانی ذاتی در JavaScript است. JSON با سربرگیافت Content-Type: application/json انتقال می‌یابد. البتناتیو‌ها شامل XML (حجیم، روبه زوال)، YAML (مناسب برای پیکربندی، نادر برای API) و Protocol Buffers (دودویی، کارآمد برای سیستم‌های با بار بالا) هستند.

ساختار شیئه JSON در REST API معمولاً شامل فیلدهای id، type و ویژگی‌های منبع است. برای کلکسیون‌ها از مصفوفه JSON با فراداده‌های صفحه‌بندی استفاده می‌شود. REST API‌های مدرن از مشخصات JSON:API (jsonapi.org) یا JSON Schema برای اعتبارسنجی پاسخ‌ها پیروی می‌کنند. استفاده از یک فرمت داده واحد توسعه کتابخانه‌های کلینتی و تولید مستندات را ساده می‌کند.

نمونه پاسخ JSON برای لیست کاربران:

{
    "data": [
        {
            "id": 1,
            "name": "آنا پتروفا",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

انتخاب فرمت انتقال داده بر عملکرد برنامه موبایل تأثیر می‌گذارد. JSON توسط GZIP تا 70–80% فشرده می‌شود که آن را برای اکثر سناریوها قابل قبول می‌کند. برای برنامه‌های بلافاصله با حجم داده زیاد (پخش جریانی، بازی‌ها) توصیه می‌شود به پروتکل‌های دودویی یا WebSocket در ترکیب با Protocol Buffers روی آوریم.

نمونه درخواست‌های REST API

بیایید نمونه‌های عملی کار با REST API را در طرف برنامه موبایل بررسی کنیم. به عنوان مثال، API برای کار با سفارش‌ها در یک فروشگاه آنلاین را در نظر می‌گیریم. برای هر روش HTTP، درخواست و پاسخ مورد انتظار سرور نمایش داده شده است. نمونه‌ها ساختار معمولی RESTful API را که در توسعه موبایل استفاده می‌شود نشان می‌دهند.

GET — دریافت لیست سفارش‌ها

درخواست برای دریافت کلیه سفارش‌های کاربر با صفحه‌بندی. پاسخ شامل یک مصفوفه از شیئ‌های سفارش و اطلاعات فراداده برای پیمایش صفحه‌ای است. پارامترهای page و per_page از طریق query string ارسال می‌شوند.

// رابط Retrofit برای REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — ایجاد سفارش جدید

ایجاد سفارش جدید از طریق درخواست POST. سرور وضعیت 201 Created و شیئه ایجادشده را در بدنه پاسخ برمی‌گرداند. مهم: ایجاد روی کلکسیون /api/v1/orders انجام می‌شود نه روی یک منبع مشخص — این یک الگوی استاندارد RESTful است.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// نمونه بدنه درخواست
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — حذف سفارش

حذف منبع با روش DELETE در URL مشخص سفارش انجام می‌شود. حذف موفق 204 No Content برمی‌گرداند. بازتاب‌پذیری DELETE به این معنی است که درخواست مجدد به همان URL 404 Not Found برمی‌گرداند که به طور صحیح در طرف کلینت پردازش می‌شود.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// استفاده در ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

این نمونه‌ها پیاده‌سازی معمولی REST API را در طرف Android با استفاده از Retrofit و Kotlin Coroutines نشان می‌دهند. برای برنامه‌های iOS، نقش مشابهی را URLSession یا کتابخانه Alamofire در ترکیب با پروتکل‌های Codable ایفا می‌کنند. ساختار REST API بدون توجه به سیستم‌عامل یکسان باقی می‌ماند — تنها روش اجرای درخواست‌ها تغییر می‌کند.

طراحی RESTful API: توصیه‌های عملی

طراحی یک RESTful API باکیفیت نیازمند پیروی از قواعدی است که API را برای برنامه‌نویسان حدسی می‌کنند. منابع باید با اسم جمع نامگذاری شوند (/users، /orders، /products)، روش‌های HTTP عملیات را منعکس کنند، و URL ساختار سلسله‌مراتب را نشان دهد. خطاها باید یک JSON استاندارد با کد و پیام باشد نه فقط HTTP وضعیت. پایبندی به این قواعد مانع ورود برنامه‌نویسان جدید را کاهش می‌دهد و ادغام را ساده می‌کند.

• نامگذاری منابع — جمع، kebab-case: /api/v1/user-orders، نه /api/v1/getUserOrders
• فیلتر و مرتب‌سازی — از طریق پارامترهای query: ?status=active&sort=created_at:desc
• صفحه‌بندی — cursor-based برای مجموعه‌های بزرگ، page-based برای کوچک
• نسخه‌بندی — از طریق URL (/api/v2/) یا سربرگیافت Accept-Version
• خطاها — فرمت واحد: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — سربرگیافت‌های X-RateLimit-Remaining و Retry-After

یکی از خطاهای رایج در طراحی REST API تودرو منابع است. به جای /users/1/orders/5/items/3 بهتر است از ساختار تخت با پارامترهای query استفاده کنید: /items?order_id=5&user_id=1. این ذخیره‌سازی را ساده، نیاز به پشتیبانی از مسیرهای طولانی در سرور را از بین می‌برد و مستندسازی را آسان می‌کند. معماری تخت با درخواست‌های graph-based در صورت انتقال به GraphQL در آینده نیز سازگارتر است.

امنیت REST API از طریق احراز هویت (JWT، OAuth 2.0) و مجوزدهی در سطح منابع پیاده‌سازی می‌شود. هر درخواست باید بررسی کند که آیا کاربر به منبع مورد نظر دسترسی دارد یا خیر. HTTPS اجباری است — بدون شیفرسازی، توکن‌ها و داده‌ها به صورت متن ساده انتقال می‌یابند. برای برنامه‌های موبایل توصیه می‌شود از OAuth 2.0 با PKCE (Proof Key for Code Exchange) برای دریافت ایمن توکن‌ها استفاده کنید.

نسخه‌بندی و ذخیره‌سازی

نسخه‌بندی REST API برای حفظ سازگاری به عقب در زمان تغییرات ضروری است. رایج‌ترین رویکردها: نسخه در URL (/api/v1/orders)، نسخه در سربرگیافت (Accept: application/vnd.myapi.v1+json) و نسخه در پارامتر query (?api_version=1). نسخه‌بندی URL محبوب‌ترین روش است به دلیل اینکه در لاگ‌ها و مستندات به وضوح قابل مشاهده است. اما این اصل REST درباره URL واحد منبع را نقض می‌کند.

ذخیره‌سازی در REST API از طریق سربرگیافت‌های HTTP Cache-Control، ETag و Last-Modified پیاده سازی می‌شود. درخواست‌های GET که به عنوان قابل ذخیره‌سازی علامت‌گذاری شده‌اند می‌توانند بدون مراجعه به سرور از ذخیره مرورگر یا پروکسی خدمت گیرند. برای برنامه‌های موبایل، ذخیره‌سازی به‌ویژه مهم است — مصرف ترافیک را کاهش می‌دهد و نمایش داده‌های قبلاً بارگیری‌شده را در اتصال ضعیف سریع‌تر می‌کند. ETag یک هش از محتوای پاسخ است: کلینت آن را در If-None-Match ارسال می‌کند و سرور در صورت تغییر نکردن داده‌ها 304 Not Modified برمی‌گرداند.

البتناتیوهای مدرن REST API شامل GraphQL (انتخاب انعطاف‌پذیر داده توسط کلینت) و gRPC (پروتکل دودویی بر روی HTTP/2 برای میکروسرویس‌ها) هستند. اما REST به دلیل سادگی، جهانگیری و پشتیبانی گسترده از ابزارها، استاندارد اصلی برای API‌های عمومی باقی مانده است. انتخاب بین REST و البتناتیو‌ها به نیازهای مشخص پروژه بستگی دارد: پیچیدگی درخواست‌ها، حجم داده‌ها، نیازمندی‌های به‌روزرسانی بلافاصله.