RESTful API Mimarisi ve Mobil Uygulama Entegrasyon Standartları

Web ve mobil platformların aynı veritabanını ve iş mantığını tutarlı biçimde paylaşabilmesi için iyi tasarlanmış bir RESTful API mimarisi büyük önem taşır. Net tanımlanmış JSON yanıt formatı, doğru kullanılan HTTP durum kodları ve katmanlı API güvenliği, entegrasyon süreçlerini daha öngörülebilir, bakımı kolay ve hatalara karşı daha dayanıklı hale getirir. Bu yazıda tufiworks olarak web ve mobil projelerimizde temel aldığımız REST API standartlarını adım adım ele alıyoruz.

RESTful API Mimarisi Nedir?

REST (Representational State Transfer), istemci ile sunucu arasındaki iletişimi kaynaklar (resources) üzerinden tanımlayan bir mimari yaklaşımdır. Her kaynak benzersiz bir URL ile temsil edilir ve bu kaynaklar üzerinde standart HTTP metotlarıyla işlem yapılır. RESTful bir API'nin temel ilkeleri şunlardır:

• İstemci-sunucu ayrımı: Arayüz (web sitesi veya mobil uygulama) ile veri katmanı birbirinden bağımsız geliştirilebilir.
• Durumsuzluk (stateless): Her istek, işlenmesi için gereken tüm bilgiyi (ör. kimlik doğrulama belirteci) kendi içinde taşır.
• Önbelleğe alınabilirlik: Yanıtlar, uygun başlıklarla önbelleğe alınabilir olarak işaretlenerek performans artırılabilir.
• Tekdüze arayüz: Kaynaklar tutarlı URL yapıları ve HTTP metotlarıyla yönetilir.
• Katmanlı sistem: İstemci, araya giren yük dengeleyici, ağ geçidi veya önbellek katmanlarından haberdar olmak zorunda değildir.

HTTP Metotları ve Kullanım Amaçları

• GET – Kaynağı okur. Örnek: GET /api/v1/products
• POST – Yeni kaynak oluşturur. Örnek: POST /api/v1/orders
• PUT – Kaynağı bütünüyle günceller.
• PATCH – Kaynağın yalnızca belirli alanlarını günceller.
• DELETE – Kaynağı siler.

URL ve Kaynak İsimlendirme Kuralları

• Kaynak adlarında fiil yerine çoğul isim kullanın: /users, /orders.
• İlişkili kaynakları hiyerarşik gösterin: /users/42/orders.
• Filtreleme, sıralama ve sayfalama için sorgu parametreleri kullanın: /products?category=shoes&sort=-price&page=2.
• Sürüm bilgisini URL'de veya başlıkta açıkça belirtin: /api/v1/.

JSON Yanıt Standartları

Web ve mobil istemcilerin aynı API'yi sorunsuz tüketebilmesi için tüm uç noktalarda tutarlı bir JSON yanıt formatı belirlemek gerekir. Tutarlı bir yapı, istemci tarafında tek bir yanıt işleyici yazılmasını sağlar ve hata ayıklamayı kolaylaştırır.

Başarılı Yanıt Örneği

{

  "success": true,

  "data": {

    "id": 42,

    "name": "Ayşe Yılmaz",

    "email": "[email protected]",

    "created_at": "2024-05-14T10:30:00Z"

  },

  "meta": {

    "request_id": "a1b2c3d4"

  }

}

Hata Yanıtı Örneği

{

  "success": false,

  "error": {

    "code": "VALIDATION_ERROR",

    "message": "E-posta adresi geçerli değil.",

    "fields": { "email": "Geçerli bir e-posta giriniz." }

  }

}

Sayfalı Liste Yanıtı Örneği

{

  "success": true,

  "data": [ { "id": 1 }, { "id": 2 } ],

  "meta": { "page": 2, "per_page": 20, "total": 135, "next_cursor": "eyJpZCI6NDB9" }

}

JSON Yanıtlarında Dikkat Edilecek Noktalar

• Tutarlı alan isimlendirmesi: snake_case veya camelCase'den birini seçip tüm API'de aynısını kullanın.
• Tarih formatı: Tarih ve saatleri ISO 8601 formatında ve UTC olarak döndürün; yerel saate dönüştürme işini istemciye bırakın.
• Null değerler: Alanın boş olduğunu belirtmek için alanı tamamen kaldırmak yerine tutarlı biçimde null kullanın.
• Makine tarafından okunabilir hata kodları: Kullanıcıya gösterilen mesajın yanında istemcinin karar verebileceği sabit bir hata kodu sağlayın.
• Gereksiz veri göndermeyin: Özellikle mobil ağlarda yanıt boyutu performansı doğrudan etkiler.

HTTP Durum Kodları Tablosu

Doğru HTTP durum kodları, istemcinin yanıtın gövdesini ayrıştırmadan önce isteğin sonucunu anlamasını sağlar. Her durumda 200 OK döndürüp hatayı yalnızca gövdede belirtmek, önbellekleme, izleme ve hata yönetimini zorlaştırır. Aşağıda en sık kullanılan durum kodlarını ve kullanım senaryolarını bulabilirsiniz:

2xx – Başarılı Yanıtlar

• 200 OK: İstek başarılı; GET, PUT veya PATCH sonrası veri döndürülür.
• 201 Created: POST ile yeni kaynak oluşturuldu; yanıtta oluşturulan kaynak veya konumu yer alır.
• 204 No Content: İşlem başarılı ancak döndürülecek içerik yok; genellikle DELETE sonrası kullanılır.

4xx – İstemci Hataları

• 400 Bad Request: İstek hatalı biçimlendirilmiş veya eksik parametre içeriyor.
• 401 Unauthorized: Kimlik doğrulama yapılmamış ya da belirteç geçersiz veya süresi dolmuş.
• 403 Forbidden: Kullanıcı kimliği doğrulanmış ancak bu kaynağa erişim yetkisi yok.
• 404 Not Found: İstenen kaynak bulunamadı.
• 409 Conflict: İstek mevcut kaynak durumuyla çakışıyor (ör. aynı e-posta ile ikinci kayıt).
• 422 Unprocessable Entity: İstek biçim olarak doğru ancak doğrulama kurallarını karşılamıyor.
• 429 Too Many Requests: Hız sınırı (rate limit) aşıldı.

5xx – Sunucu Hataları

• 500 Internal Server Error: Sunucuda beklenmeyen bir hata oluştu.
• 502 Bad Gateway: Ağ geçidi veya proxy, arka uç sunucudan geçerli yanıt alamadı.
• 503 Service Unavailable: Servis geçici olarak kullanılamıyor (bakım veya aşırı yük).

Mobil uygulamalarda bu ayrım özellikle önemlidir: Örneğin 401 yanıtı alındığında uygulama otomatik olarak belirteç yenileme akışını başlatabilir, 503 veya 429 yanıtlarında ise isteği belirli bir bekleme süresinden sonra yeniden deneyebilir.

API Güvenliği: JWT ve OAuth 2.0

API güvenliği, hem web hem mobil istemcilerin aynı veri katmanına eriştiği projelerde tek bir önlemle değil, birbirini tamamlayan katmanlarla sağlanır.

JWT (JSON Web Token) ile Kimlik Doğrulama

JWT, kullanıcı kimliği ve yetki bilgilerini imzalı bir belirteç içinde taşıyan, durumsuz REST mimarisine uygun bir yöntemdir. İstemci, her istekte belirteci başlıkta gönderir:

GET /api/v1/profile

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• Kısa ömürlü erişim belirteçleri kullanın ve oturumu yenileme (refresh) belirteçleriyle sürdürün.
• JWT içeriği imzalıdır ancak varsayılan olarak şifreli değildir; belirteç içine hassas bilgi koymayın.
• Yenileme belirteçlerini sunucu tarafında iptal edilebilir şekilde yönetin.

OAuth 2.0 ile Yetkilendirme

OAuth 2.0, üçüncü taraf girişleri (Google, Apple vb.) ve farklı istemcilere kontrollü erişim vermek için yaygın kabul görmüş bir yetkilendirme çerçevesidir. Mobil ve tek sayfa web uygulamalarında istemci gizli anahtarı güvenle saklanamadığından Authorization Code akışının PKCE ile birlikte kullanılması önerilir.

Temel Güvenlik Kontrol Listesi

• Tüm trafiği HTTPS (TLS) üzerinden yönlendirin.
• API anahtarlarını ve gizli bilgileri mobil uygulama paketine gömmeyin.
• Mobil cihazda belirteçleri iOS Keychain veya Android Keystore gibi güvenli depolama alanlarında saklayın.
• Tüm girdileri sunucu tarafında doğrulayın; istemci tarafı doğrulamaya güvenmeyin.
• Hız sınırlaması (rate limiting) ile kaba kuvvet ve kötüye kullanım girişimlerini sınırlayın.
• Web istemcileri için CORS politikalarını yalnızca gerekli alan adlarına izin verecek şekilde yapılandırın.
• Erişim kayıtlarını tutun ve olağandışı davranışları izleyin.

Mobil Uygulama API Entegrasyonu İçin En İyi Uygulamalar

Mobil uygulama API entegrasyonu, web entegrasyonundan bazı noktalarda ayrışır. Mobil kullanıcılar değişken ağ koşullarında çalışır ve uygulamanın eski sürümleri uzun süre kullanımda kalabilir.

1. API sürümleme: Mağaza güncellemeleri tüm kullanıcılara aynı anda ulaşmadığından, geriye dönük uyumluluğu bozan değişiklikleri yeni sürüm altında (/api/v2/) yayınlayın.
2. Sayfalama: Büyük listeleri parça parça döndürün; sonsuz kaydırma senaryolarında imleç (cursor) tabanlı sayfalama daha tutarlı sonuç verir.
3. Yanıt boyutunu optimize edin: Sıkıştırma (gzip) kullanın ve istemcinin ihtiyaç duyduğu alanları seçebilmesine olanak tanıyın.
4. Idempotency: Bağlantı kopması sonrası tekrar gönderilen ödeme veya sipariş isteklerinin mükerrer kayıt oluşturmaması için idempotency anahtarları kullanın.
5. Yeniden deneme stratejisi: Geçici hatalarda artan bekleme süreli (exponential backoff) yeniden deneme uygulayın.
6. Önbellekleme: ETag ve Cache-Control başlıklarıyla gereksiz veri transferini azaltın.

Web ve Mobil API Tasarımında Ortak Mimari

Başarılı bir web ve mobil API tasarımı, iki platformun aynı iş kurallarını ve aynı veritabanını tek bir kaynaktan kullanmasını sağlar. Bu yaklaşımın sağladığı başlıca avantajlar:

• İş mantığı tek bir yerde tutulduğu için platformlar arası tutarsızlık riski azalır.
• Yeni bir istemci (ör. tablet uygulaması veya iş ortağı entegrasyonu) mevcut API üzerine daha hızlı eklenebilir.
• Güvenlik ve izleme politikaları merkezi olarak yönetilir.
• Ön yüz ve arka yüz ekipleri, belgelenmiş bir sözleşme üzerinden paralel çalışabilir.

Bu sözleşmeyi netleştirmek için OpenAPI (Swagger) gibi bir belgeleme standardı kullanmak, ekipler arasındaki iletişimi kolaylaştırır ve test süreçlerini hızlandırır.

Sonuç

Sağlam bir RESTful API mimarisi; tutarlı JSON yanıtları, anlamlı HTTP durum kodları, katmanlı güvenlik ve mobil odaklı en iyi uygulamalarla birleştiğinde, web ve mobil platformların aynı veritabanını güvenli ve verimli biçimde paylaşmasına zemin hazırlar. tufiworks olarak projelerimizde bu standartları baştan planlayarak, ölçeklenebilir ve bakımı kolay entegrasyonlar kurmayı hedefliyoruz.