REST API: nedir, HTTP yöntemleri ve mobil uygulamalarda çalışma prensibi

REST API Nedir?

REST API (Temsili Durum Aktarımı API'si), Roy Fielding tarafından 2000 yılındaki doktora tezinde önerilen bir mimari tarzdır. Ağ protokolleri tasarlamak için bir dizi kısıtlama ve ilke tanımlar. Bu kısıtlamalara uyan API'ye RESTful denir. REST bir protokol veya standart değildir — istemci ve sunucu arasında veri alışverişi için mevcut protokolleri (çoğunlukla HTTP) kullanan bir mimari yaklaşımdır.

REST'in temel fikri kaynak odaklı mimaridir. Sunucuda yöntem çağırmak yerine (SOAP veya RPC'de olduğu gibi), istemci kaynaklar üzerinde işlem yapar: listeler alır, yenilerini oluşturur, günceller veya siler. Her kaynak bir alan varlığıdır: kullanıcı, sipariş, ürün, makale. Bir kaynağın, istemciye standartlaştırılmış bir biçimde (genellikle JSON) iletilen bir durumu vardır. Sunucu, istekler arasında istemci durumunu saklamaz — bu, REST'in temel bir gereksinimi olan durumsuzluk (stateless) ilkesidir.

REST API'nin temel özellikleri:

• Stateless — istemciden gelen her istek, işlenmesi için gerekli tüm bilgileri içerir
• Cacheable — sunucu yanıtları, önbelleğe alınabilir veya alınamaz olarak açıkça işaretlenmelidir
• Layered system — mimari, ara sunucular, yük dengeleyiciler, proxy'ler içerebilir
• Uniform interface — HTTP yöntemleri, URL'ler ve durum kodları aracılığıyla birleşik bir etkileşim arayüzü

REST Mimarisi İlkeleri

REST, Fielding tarafından formüle edilen altı mimari kısıtlamaya dayanır. Bu kısıtlamalara uyum, ölçeklenebilirlik, performans ve entegrasyon kolaylığı sağlar. Her ilke, dağıtık sistemlerin belirli bir sorununu — önbellekleme ihtiyacından güvenlik gereksinimlerine kadar — çözer. Her ilkeyi ayrıntılı olarak inceleyelim.

Uniform Interface ilkesi ayrıca dört alt kısıtlama içerir: URI aracılığıyla kaynak tanımlama, temsiller aracılığıyla kaynak yönetimi, kendini tanımlayan mesajlar ve HATEOAS (Uygulama Durumunun Motoru Olarak Hiper Ortam). Son alt kısıtlama pratikte sıklıkla göz ardı edilir — modern REST API'lerinin çoğu HATEOAS'ı tam olarak uygulamaz ve bu da böyle bir API'nin “gerçekten” RESTful olup olmadığı konusunda tartışmalara yol açar.

Stateless ilkesi ölçekleme için en önemlilerinden biridir. Sunucuda oturumların olmaması, herhangi bir sunucu örneğinin herhangi bir isteği işleyebileceği anlamına gelir. Bu, yatay ölçeklemeyi basitleştirir: yük dengeleyicinin arkasına yeni sunucular eklemeniz yeterlidir. Mobil uygulamalar için durumsuzluk ayrıca bir isteğin herhangi bir CDN sunucusuna gönderilebileceği anlamına gelir ve bu da küresel kullanılabilirlik için kritiktir.

REST'te HTTP Yöntemleri

REST API'deki her HTTP yöntemi, bir kaynak üzerinde belirli bir işleme karşılık gelir: okuma için GET, oluşturma için POST, tam güncelleme için PUT, kısmi güncelleme için PATCH, silme için DELETE. Yöntemlerin idempotansı (tekrar edilebilirliği) önemli bir özelliktir: GET, PUT, DELETE idempotenttir (tekrarlanan yürütme aynı sonucu verir), POST ve PATCH değildir. Bu, isteğin sunucuya ulaşıp ulaşmadığını istemcinin bilmediği ağ hatalarını işlemek için önemlidir.

• GET — bir kaynağı veya kaynak listesini alma. Idempotent, sunucu durumunu değiştirmez
• POST — yeni bir kaynak oluşturma. Idempotent değil, her çağrı yeni bir kaynak oluşturur
• PUT — kaynağın tamamen değiştirilmesi. Idempotent, ilkinden sonra tekrarlanan çağrılar durumu değiştirmez
• PATCH — kaynağın kısmi güncellemesi. Kısmen idempotent (uygulamaya bağlıdır)
• DELETE — kaynağı silme. Idempotent, tekrarlanan silme 404 döndürür, hata değil

HTTP durum kodları REST API'nin ayrılmaz bir parçasıdır. Her kod belirli bir anlam taşır: başarılı GET için 200 OK, POST için 201 Created, yanıt gövdesi olmayan DELETE için 204 No Content, geçersiz veriler için 400 Bad Request, kimlik doğrulama eksikliğinde 401 Unauthorized, kaynak bulunamadığında 404 Not Found. Durum kodlarının doğru kullanımı API'yi kendi kendini belgeleyen yapar ve hata ayıklamayı basitleştirir.

Veri Biçimleri: JSON ve Diğerleri

JSON (JavaScript Nesne Gösterimi), REST API'de veri aktarımı için birincil biçimdir. Popülerliği basitliğinden, insan tarafından okunabilirliğinden ve JavaScript'teki yerel desteğinden kaynaklanmaktadır. JSON, Content-Type: application/json başlığı ile iletilir. Alternatifler arasında XML (ayrıntılı, eskimekte olan), YAML (yapılandırma için uygun, API'ler için daha az yaygın) ve Protocol Buffers (ikili, yüksek yüklü sistemler için verimli) bulunur.

REST API'deki bir JSON nesnesinin yapısı genellikle id, type alanlarını ve kaynak özniteliklerini içerir. Koleksiyonlar için, sayfalama meta verileriyle birlikte bir JSON dizisi kullanılır. Modern REST API'leri, yanıt doğrulaması için JSON:API belirtimini (jsonapi.org) veya JSON Schema'yı takip eder. Birleşik bir veri biçimi kullanmak, istemci kitaplığı geliştirmeyi ve belge oluşturmayı basitleştirir.

Kullanıcı listesi için JSON yanıtı örneği:

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

Veri aktarım biçimi seçimi, mobil uygulama performansını etkiler. JSON, GZIP ile %70-80 oranında sıkıştırılır ve bu da onu çoğu senaryo için kabul edilebilir kılar. Büyük veri hacimlerine (akış, oyun) sahip gerçek zamanlı uygulamalar için, ikili protokollere geçilmesi veya Protocol Buffers ile birlikte WebSocket kullanılması önerilir.

REST API İstek Örnekleri

Mobil uygulama tarafında REST API ile çalışmanın pratik örneklerine bakalım. Örnek olarak, bir çevrimiçi mağazadaki siparişlerle çalışmak için bir API alalım. Her HTTP yöntemi için bir istek ve beklenen sunucu yanıtı gösterilmiştir. Örnekler, mobil geliştirmede kullanılan tipik RESTful API yapısını göstermektedir.

GET — sipariş listesini alma

Sayfalama ile tüm kullanıcı siparişlerini almak için bir istek. Yanıt, sipariş nesnelerinin bir dizisini ve sayfa gezinmesi için meta bilgileri içerir. page ve per_page parametreleri sorgu dizesi aracılığıyla iletilir.

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

POST — yeni sipariş oluşturma

POST isteğiyle yeni bir sipariş oluşturma. Sunucu, 201 Created durumunu ve yanıt gövdesinde oluşturulan nesneyi döndürür. Önemli: oluşturma, belirli bir kaynakta değil, /api/v1/orders koleksiyonunda yapılır — bu standart RESTful desenidir.

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

// İstek Gövdesi Örneği
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — siparişi silme

Bir kaynağın silinmesi, belirli sipariş URL'sinde DELETE yöntemiyle yapılır. Başarılı silme 204 No Content döndürür. DELETE'ın idempotansı, aynı URL'ye tekrarlanan isteğin 404 Not Found döndüreceği anlamına gelir ve bu, istemcide doğru şekilde işlenir.

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

// ViewModel'de Kullanım
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Bu örnekler, Retrofit ve Kotlin Coroutines kullanarak Android tarafında tipik bir REST API uygulamasını göstermektedir. iOS uygulamaları için URLSession veya Alamofire kitaplığı, Codable protokolleriyle birlikte benzer bir rol oynar. REST API yapısı platformdan bağımsız olarak aynı kalır — yalnızca istek yapma şekli değişir.

RESTful API Tasarımı: Pratik Öneriler

Kaliteli bir RESTful API tasarlamak, API'yi geliştiriciler için sezgisel hale getiren kurallara uymayı gerektirir. Kaynaklar çoğul isimlerle (/users, /orders, /products) adlandırılmalı, HTTP yöntemleri işlemleri yansıtmalı ve URL'ler iç içe geçme hiyerarşisini temsil etmelidir. Hatalar, yalnızca bir HTTP durumu değil, kod ve mesaj içeren standartlaştırılmış bir JSON döndürmelidir. Bu kurallara uymak, yeni geliştiriciler için giriş engelini düşürür ve entegrasyonu basitleştirir.

• Kaynak adlandırma — çoğul, kebab-case: /api/v1/user-orders, /api/v1/getUserOrders değil
• Filtreleme ve sıralama — sorgu parametreleri aracılığıyla: ?status=active&sort=created_at:desc
• Sayfalama — büyük kümeler için imleç tabanlı, küçükler için sayfa tabanlı
• Sürümleme — URL (/api/v2/) veya Accept-Version başlığı aracılığıyla
• Hatalar — birleşik biçim: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Hız sınırlama — X-RateLimit-Remaining ve Retry-After başlıkları

REST API tasarlarken sık yapılan bir hata, aşırı kaynak iç içe geçmesidir. /users/1/orders/5/items/3 yerine, sorgu parametreleriyle düz bir yapı kullanmak daha iyidir: /items?order_id=5&user_id=1. Bu, önbelleklemeyi basitleştirir, sunucuda uzun yolların korunmasını gerektirmez ve belgelemeyi kolaylaştırır. Düz mimari, gelecekte GraphQL'ye geçiş yaparken grafik tabanlı sorgularla daha iyi uyumludur.

REST API güvenliği, kimlik doğrulama (JWT, OAuth 2.0) ve kaynak düzeyinde yetkilendirme yoluyla uygulanır. Her istek, kullanıcının istenen kaynağa erişimi olup olmadığını kontrol etmelidir. HTTPS zorunludur — şifreleme olmadan, token'lar ve veriler düz metin olarak iletilir. Mobil uygulamalar için, güvenli token alımı için PKCE (Proof Key for Code Exchange) ile OAuth 2.0 kullanılması önerilir.

Sürümleme ve Önbellekleme

REST API'nin sürümlemesi, değişiklikler sırasında geriye dönük uyumluluk için gereklidir. En yaygın yaklaşımlar şunlardır: URL'de sürüm (/api/v1/orders), başlıkta sürüm (Accept: application/vnd.myapi.v1+json) ve sorgu parametresinde sürüm (?api_version=1). URL sürümlemesi en popüler yöntemdir çünkü günlüklerde ve belgelerde açıkça görülebilir. Ancak, kaynak başına tek bir URL olması REST ilkesini ihlal eder.

REST API'de önbellekleme, HTTP başlıkları Cache-Control, ETag ve Last-Modified aracılığıyla uygulanır. Önbelleğe alınabilir olarak işaretlenen GET istekleri, sunucuya başvurmadan tarayıcı veya proxy önbelleğinden sunulabilir. Mobil uygulamalar için önbellekleme özellikle önemlidir — veri kullanımını azaltır ve zayıf bağlantıda önceden yüklenmiş verilerin görüntülenmesini hızlandırır. ETag, yanıt içeriğinin bir karmasıdır: istemci bunu If-None-Match'te gönderir ve veriler değişmemişse sunucu 304 Not Modified döndürür.

REST API'nin modern alternatifleri arasında GraphQL (istemci tarafında esnek veri çekme) ve gRPC (mikro hizmetler için HTTP/2 üzerinde ikili protokol) bulunur. Bununla birlikte REST, basitliği, evrenselliği ve kapsamlı araç desteği sayesinde genel API'ler için birincil standart olmaya devam etmektedir. REST ve alternatifler arasındaki seçim, projenin belirli gereksinimlerine (sorgu karmaşıklığı, veri hacmi, gerçek zamanlı güncelleme ihtiyaçları) bağlıdır.