REST API: bu nədir, HTTP metodları və mobil tətbiqlərdə işləmə prinsipi

REST API nədir?

REST API (Representational State Transfer API) — 2000-ci ildə Roy Fielding tərəfindən doktorluq dissertasiyasında təklif edilmiş memarlıq üslubudur. O, şəbəkə protokollarının layihələndirilməsi üçün məhdudiyyətlər və prinsiplər dəsti müyyənləşdirir. Bu məhdudiyyətlərə uyğun API RESTful adlanır. REST protokol və ya standart deyil — bu, müştəri və server arasında məlumat mübadiləsi üçün mövcud protokollardan (əsasən HTTP) istifadə edən memarlıq yanaşmasıdır.

REST-in əsas ideyası resurs yönümlü memarlıqdır. Serverdə metodları çağırmaq əvəzinə (SOAP və ya RPC-də olduğu kimi), müştəri resurslar üzərində əməliyyat aparır: onların siyahısını alır, yenilərini yaradır, yeniləyir və ya silir. Hər bir resurs mövzu sahəsinin varlığıdır: istifadəçi, sifariş, məhsul, məqalə. Resursun vəziyyəti standartlaşdırılmış formatda, adətən JSON vasitəsilə müştəriyə ötürülür. Server sorğular arasında müştərinin vəziyyətini saxlamır — bu, stateless prinsipi, REST-in əsas tələbidir.

REST API-nin əsas xüsusiyyətləri:

• Stateless — müştəridən gələn hər sorğu emal üçün lazım olan bütün məlumatı ehtiva edir
• Cacheable — server cavabları açıq şəkildə keşlənən və ya keşlənməyən olaraq qeyd edilməlidir
• Layered system — memarlıq aralıq serverlər, balanslaşdırıcılar, proxilər ehtiva edə bilər
• Uniform interface — HTTP metodları, URL və status kodları vasitəsilə vahid qarşılıqlı əlaqə interfeysi

REST memarlığının prinsipləri

REST Fielding tərəfindən formalaşdırılmış altı memarlıq məhdudiyyətinə əsaslanır. Bu məhdudiyyətlərə riayət etmək miqyaslana bilmə, performans və inteqrasiya asanlığını təmin edir. Hər bir prinsip paylanmış sistemlərin konkret problemini həll edir — keşləmə ehtiyacından tutmuş təhlükəsizlik tələblərinə qədər. Hər prinsipi ətraflı nəzərdən keçirək.

Uniform Interface prinsipi əlavə olaraq dörd alt-məhdudiyyəti ehtiva edir: resursların URI vasitəsilə identifikasiyası, təsvirlər vasitəsilə resurslarla manipulyasiya, özünü təsvir edən mesajlar və HATEOAS (hipermedia tətbiq vəziyyətinin məhərriki kimi). Sonuncu alt-məhdudiyyət praktikada tez-tez göz ardı edilir — müasir REST API-lərin əksəriyyəti HATEOAS-ı tam tətbiq etmir və bu, belə bir API-in „həqiqi” RESTful olub-olmaması ilə bağlı müzakirələrə səbəb olur.

Stateless prinsipi miqyaslama üçün ən vaciblərdən biridir. Serverdə sessiyaların olmaması o deməkdir ki, serverin istənilən nüsxəsi istənilən sorğunu emal edə bilər. Bu, üfqi miqyaslamanı sadələşdirir: balanslaşdırıcının arxasına yeni serverlər əlavə etmək kifayətdir. Mobil tətbiqlər üçün stateless eyni zamanda sorğun istənilən CDN serverinə göndərilə biləcəyi mənasını verir ki, bu da qlobal əlçatanlıq üçün kritik əhəmiyyət kəsb edir.

REST-də HTTP metodları

REST API-dəki hər bir HTTP metodu resurs üzərində müəyyən bir əməliyyata uyğun gəlir: GET oxumaq üçün, POST yaratmaq üçün, PUT tam yeniləmə üçün, PATCH qismən yeniləmə üçün, DELETE silmək üçün. Metodların idempotentliyi əsas xarakteristikadır: GET, PUT, DELETE idempotentdir (təkrar icra eyni nəticəni verir), POST və PATCH isə yox. Bu, şəbəkə xətalarının idarə edilməsi üçün vacibdir — müştəri sorğun serverə çatıb-çatmadığını bilmədikdə.

• GET — resurs və ya resurslar siyahısını almaq. İdempotentdir, server vəziyyətini dəyişmir
• POST — yeni resurs yaratmaq. İdempotent deyil, hər çağırış yeni resurs yaradır
• PUT — resursun tam əvəz edilməsi. İdempotentdir, təkrari çağırış birincidən sonra vəziyyəti dəyişmir
• PATCH — resursun qismən yenilənməsi. Qismən idempotentdir (tətbiqdən asılıdır)
• DELETE — resursun silinməsi. İdempotentdir, təkrari silmə 404 qaytarır, xəta deyil

HTTP status kodları REST API-in ayrılmaz hissəsidir. Hər bir kod müəyyən məna daşıyır: 200 OK uğurlu GET üçün, 201 Created POST üçün, 204 No Content cavab gövdəsiz DELETE üçün, 400 Bad Request etibarsız məlumatlarda, 401 Unauthorized autentifikasiya olmadıqda, 404 Not Found resurs tapılmadıqda. Status kodlarının düzgün istifadəsi API-i özünü sənədləşdirən edir və debug prosesini sadələşdirir.

Məlumat formatları: JSON və digərləri

JSON (JavaScript Object Notation) — REST API-də məlumat ötürmənin əsas formatıdır. Onun populyarlığı sadəliyi, insan tərəfindən oxuna bilməsi və JavaScript-də native dəstəyi ilə izah olunur. JSON Content-Type: application/json başlığı ilə ötürülür. Alternativlərə XML (həcmli, köhnələn), YAML (konfiqurasiya üçün rahat, API üçün nadir) və Protocol Buffers (binar, yüksək yüklü sistemlər üçün səmərəli) daxildir.

REST API-də JSON obyektinin strukturu adətən id, type sahələrini və resurs atributlarını ehtiva edir. Kolleksiyalar üçün paginasiya metadatası olan JSON massivi istifadə olunur. Müasir REST API-lər cavabların validasiyası üçün JSON:API (jsonapi.org) və ya JSON Schema spesifikasiyasına əməl edir. Vahid məlumat formatının istifadəsi müştəri kitabxanalarının hazırlanmasını və sənədləşdirmənin generasiyasını sadələşdirir.

İstifadəçi siyahısı üçün JSON cavab nümunəsi:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Məlumat ötürmə formatının seçimi mobil tətbiqin performansına təsir edir. JSON GZIP vasitəsilə 70–80% sıxılır ki, bu da onu əksər ssenarilər üçün qəbul ediləbilir edir. Böyük həcmli məlumatları olan real-vaxt tətbiqləri (streaming, oyunlar) üçün binar protokollara keçmək və ya Protocol Buffers ilə birlikdə WebSocket istifadə etmək tövsiyə olunur.

REST API sorğularının nümunələri

Mobil tətbiq tərəfində REST API ilə işin praktiki nümunələrinə baxaq. Nümunə olaraq onlayn mağazada sifarişlərlə işləmək üçün API-i götürək. Hər HTTP metodu üçün sorğu və gözlənən server cavabı göstərilmişdir. Nümunələr mobil inkişafda istifadə olunan tipik RESTful API strukturunu nümayiş etdirir.

GET — sifarişlər siyahısını almaq

Paginasiya ilə istifadəçinin bütün sifarişlərini almaq üçün sorğu. Cavab sifariş obyektlərinin massivini və səhifələmə naviqasiyası üçün meta-məlumatları ehtiva edir. Page və per_page parametrləri query string vasitəsilə ötürülür.

// Retrofit interfeysi REST API üçün
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — yeni sifarişin yaradılması

POST sorğu vasitəsilə yeni sifarişin yaradılması. Server 201 Created statusu və cavab gövdəsində yaradılmış obyekti qaytarır. Vacib: yaratma /api/v1/orders kolleksiyasına edilir, konkret resursa deyil — bu standart RESTful nümunəsidir.

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

// Sorğu gövdəsi nümunəsi
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — sifarişin silinməsi

Resursun silinməsi sifarişin konkret URL-şə DELETE metodu ilə həyata keçirilir. Uğurlu silmə 204 No Content qaytarır. DELETE-in idempotentliyi o deməkdir ki, eyni URL-ə təkrari sorğu 404 Not Found qaytaracaq və bu, müştəri tərəfində düzgün idarə olunur.

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

// ViewModel-də istifadə
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Bu nümunələr Android tərəfində Retrofit və Kotlin Coroutines istifadə edərək REST API-in tipik tətbiqini nümayiş etdirir. iOS tətbiqləri üçün analog rolunu URLSession və ya Codable protokolları ilə birlikdə Alamofire kitabxanası oynayır. REST API strukturu platformadan asılı olmayaraq eyni qalır — yalnız sorğuların yerinə yetirilmə üsulu dəyişir.

RESTful API dizaynı: praktiki tövsiyələr

Keyfiyyətli RESTful API-in layihələndirilməsi API-i proqramçılar üçün intuitiv edən konvensiyalara riayət etməyi tələb edir. Resurslar cəmdə isimlərlə adlandırılmalıdır (/users, /orders, /products), HTTP metodları əməliyyatları əks etdirməli, URL-lər isə iyerarxik quruluşu göstərməlidir. Xətalar kod və mesaj ilə standartlaşdırılmış JSON qaytarmalı, sadəcə HTTP statusu yox. Bu konvensiyalara riayət yeni proqramçılar üçün giriş həddini aşağı salır və inteqrasiyanı sadələşdirir.

• Resursların adlandırılması — cəm sayı, kebab-case: /api/v1/user-orders, /api/v1/getUserOrders deyil
• Filtrləmə və sıralama — query parametrləri vasitəsilə: ?status=active&sort=created_at:desc
• Paginasiya — böyük dəstlər üçün cursor-based, kiçiklər üçün page-based
• Versiyalaşdırma — URL (/api/v2/) və ya Accept-Version başlığı vasitəsilə
• Xətalar — vahid format: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — X-RateLimit-Remaining və Retry-After başlıqları

REST API-in layihələndirilməsində tez-tez rast gəlinən səhvlərdən biri resursların həddən artıq iç-içə yerləşdirməsidir. /users/1/orders/5/items/3 əvəzinə query parametrləri ilə düz struktur istifadə etmək daha yaxşıdır: /items?order_id=5&user_id=1. Bu, keşləməni sadələşdirir, serverdə uzun yolların dəstəklənməsini tələb etmir və sənədləşdirməni asanlaşdırır. Düz memarlıq gələcəkdə GraphQL-ə keçid zamanı graph-based sorğularla daha yaxşı uyğunlaşır.

REST API təhlükəsizliyi autentifikasiya (JWT, OAuth 2.0) və resurs səviyyəsində avtorizasiya vasitəsilə həyata keçirilir. Hər sorğu istifadəçinin tələb olunan resursa çıxışının olub-olmadığını yoxlamalıdır. HTTPS məcburidir — şifrələmə olmadan tokenlər və məlumatlar açıq şəkildə ötürülür. Mobil tətbiqlər üçün tokenlərin təhlükəsiz əldə edilməsi məqsədilə OAuth 2.0-dan PKCE (Proof Key for Code Exchange) ilə istifadə etmək tövsiyə olunur.

Versiyalaşdırma və keşləmə

REST API-in versiyalaşdırılması dəyişikliklər zamanı geriyə uyğunluğu qorumaq üçün zəruridir. Ən geniş yayılmış yanaşmalar: URL-də versiya (/api/v1/orders), başlıqda versiya (Accept: application/vnd.myapi.v1+json) və query parametrində versiya (?api_version=1). URL versiyalaşdırması ən populyar üsuldur, çünki loglarda və sənədləşdirmədə açıq görünür. Lakin bu, REST-in vahid resurs URL prinsipini pozur.

REST API-də keşləmə HTTP Cache-Control, ETag və Last-Modified başlıqları vasitəsilə həyata keçirilir. Keşlənən olaraq qeyd edilmiş GET sorğuları serverə müraciət etmədən brauzerin və ya proxy-nin keşindən xidmət göstərə bilər. Mobil tətbiqlər üçün keşləmə xüsusilə vacibdir — trafik istehlakını azaldır və zəif əlaqədə əvvəlcədən yüklənmiş məlumatların göstərilməsini sürətləndirir. ETag cavab məzmununun heşidir: müştəri onu If-None-Match-də göndərir, server isə məlumat dəyişməyibsə 304 Not Modified qaytarır.

REST API-in müasir alternativlərinə GraphQL (müştəri tərəfindən çevik məlumat seçimi) və gRPC (mikroxidmətlər üçün HTTP/2 üzərində binar protokol) daxildir. Lakin REST, sadəliyi, universallığı və geniş alət dəstəyi sayəsində açıq API-lər üçün əsas standart olaraq qalır. REST və alternativlər arasında seçim layihənin konkret tələblərindən asılıdır: sorğuların mürəkkəbliyi, məlumatların həcmi, real-vaxt yenilənmə tələbləri.