* Nasıl Yapılır?

Modern mobil uygulama geliştirme süreçlerinde, dinamik veri akışı sağlamak ve kullanıcı deneyimini en üst düzeye çıkarmak için harici sunucularla iletişim kurmak hayati bir önem taşır. Mobil uygulamaların büyük bir kısmı, arka plan (backend) servisleri ile veri alışverişi yapmak amacıyla RESTful API yapılarını kullanır. Google tarafından geliştirilen ve 2026 yılında da sektörün lider çoklu platform (cross-platform) çerçevesi olmaya devam eden Flutter, güçlü asenkron programlama yetenekleri ve zengin paket ekosistemi sayesinde API entegrasyonunu oldukça pratik hale getirmektedir.

Bu kapsamlı eğitim rehberinde, Flutter projelerinizde profesyonel düzeyde API entegrasyonu nasıl yapılır sorusuna adım adım yanıt bulacaksınız. Sektör standardı haline gelen Dio kütüphanesini kullanarak, temiz mimari (clean architecture) prensiplerine uygun, güvenli, sürdürülebilir ve yüksek performanslı bir ağ katmanını sıfırdan inşa edeceğiz. Bu makale, temel Dart bilgisine sahip olan ve uygulamalarını gerçek dünya verileriyle dinamik hale getirmek isteyen orta ve ileri düzey mobil yazılım geliştiricileri için hazırlanmıştır.

Eğitim boyunca sadece basit HTTP istekleri göndermekle kalmayacak; aynı zamanda JSON verilerini güvenli bir şekilde Dart nesnelerine dönüştürmeyi (deserialization), hata yönetimini (error handling), istek kesicileri (interceptors) ve kullanıcı arayüzünde (UI) yüklenme ile hata durumlarını asenkron olarak yönetmeyi öğreneceksiniz. Hazırsanız, modern Flutter mimarisinin en önemli yapı taşlarından biri olan API entegrasyonu yolculuğumuza başlayalım.

Ön Hazırlık ve Gereksinimler

Flutter ile API entegrasyonuna başlamadan önce, geliştirme ortamınızın ve projenizin doğru yapılandırıldığından emin olmanız gerekir. 2026 yılı standartlarında, Dart dilinin güçlü tip güvenliği (type safety) ve null-safety (boş değer güvenliği) özelliklerinden tam olarak yararlanabilmek için güncel bir Flutter SDK sürümü kullanıyor olmalısınız.

Bu rehberdeki adımları uygulamak için aşağıdaki gereksinimleri karşıladığınızdan emin olun:

• Bilgisayarınızda Flutter SDK (Sürüm 3.30 veya üzeri) kurulu olmalıdır.
• Tercihen VS Code veya Android Studio editörlerinden biri ve güncel Flutter/Dart eklentileri yüklü olmalıdır.
• Test istekleri gönderebileceğimiz güvenilir bir sahte (mock) API servisi. Bu rehberde popüler ve ücretsiz bir servis olan JSONPlaceholder (https://jsonplaceholder.typicode.com) API'sini kullanacağız.
• İnternet bağlantısı olan aktif bir simülatör, emülatör veya fiziksel test cihazı.

Projenizin bağımlılıklarını yönettiğimiz pubspec.yaml dosyasına, HTTP isteklerimizi yöneteceğimiz gelişmiş ağ istemcisi olan dio paketini eklememiz gerekiyor. Standart http paketi yerine dio tercih etmemizin sebebi; interceptor desteği, küresel yapılandırma kolaylığı, istek iptal edebilme ve gelişmiş hata yönetimi gibi kurumsal düzeyde ihtiyaç duyulan özellikleri yerleşik olarak sunmasıdır.

Adım 2: Dart Model Sınıflarının Oluşturulması ve JSON Serileştirme

API'lerden gelen yanıtlar genellikle JSON (JavaScript Object Notation) formatındadır. Dart dilinde bu verileri doğrudan harita (Map) yapısı olarak kullanmak, yazım hatalarına davetiye çıkarır ve derleme zamanı (compile-time) güvenliğini ortadan kaldırır. Bu nedenle, API'den dönecek her JSON şablonu için birer Dart model sınıfı oluşturmalı ve gelen veriyi bu sınıflara dönüştürmeliyiz.

JSONPlaceholder servisinin /posts uç noktasından (endpoint) dönecek veriyi karşılamak için bir model sınıfı tasarlayacağız. Bu veri yapısında her bir gönderi; userId, id, title ve body alanlarını içerir.

Aşağıdaki kod örneğinde, null-safety uyumlu, JSON verisini Dart nesnesine (deserialization) ve Dart nesnesini tekrar JSON verisine (serialization) dönüştürebilen güvenli bir model sınıfı tanımlanmıştır:

class PostModel {
  final int userId;
  final int id;
  final String title;
  final String body;

  PostModel({
    required this.userId,
    required this.id,
    required this.title,
    required this.body,
  });

  // JSON verisini Dart nesnesine dönüştüren factory yapıcı metodu
  factory PostModel.fromJson(Map json) {
    return PostModel(
      userId: json['userId'] as int? ?? 0,
      id: json['id'] as int? ?? 0,
      title: json['title'] as String? ?? '',
      body: json['body'] as String? ?? '',
    );
  }

  // Dart nesnesini JSON formatına dönüştüren metot
  Map toJson() {
    return {
      'userId': userId,
      'id': id,
      'title': title,
      'body': body,
    };
  }
}

Yukarıdaki kod bloğunda kullanılan as int? ?? 0 gibi ifadeler, API'den gelebilecek olası eksik veya hatalı (null) verilere karşı uygulamamızın çökmesini engeller. Bu pratik, savunma odaklı kodlama (defensive programming) yaklaşımının önemli bir parçasıdır ve üretim (production) ortamındaki uygulamaların kararlılığını doğrudan artırır.

Adım 4: HTTP POST İstekleri ile Sunucuya Veri Gönderme

Uygulamalar sadece sunucudan veri okumaz, aynı zamanda sunucuya yeni veriler de gönderir. Kullanıcı kayıt formları, yeni bir gönderi oluşturma veya veri güncelleme gibi işlemler için HTTP POST yöntemi kullanılır. POST isteklerinde göndermek istediğimiz veri, isteğin gövdesinde (request body) JSON formatında sunucuya iletilir.

Aşağıdaki kod örneğinde, hazırladığımız PostModel nesnesini parametre olarak alan ve bunu JSON formatında sunucuya göndererek yeni bir kayıt oluşturan POST metodu gösterilmektedir:

  // Sunucuya yeni bir gönderi ekleyen POST metodu
  Future createPost(PostModel post) async {
    try {
      final response = await _dio.post(
        '/posts',
        data: post.toJson(),
      );

      if (response.statusCode == 201) {
        // HTTP 201: Created (Başarıyla Oluşturuldu) anlamına gelir
        return PostModel.fromJson(response.data);
      } else {
        throw Exception('Gönderi oluşturulamadı: ${response.statusCode}');
      }
    } on DioException catch (e) {
      throw Exception('Gönderi oluşturulurken ağ hatası: ${e.message}');
    } catch (e) {
      throw Exception('Gönderi oluşturulurken beklenmeyen hata: $e');
    }
  }

POST işlemlerinde sunucunun başarılı bir kayıt sonrasında genellikle HTTP 201 durum kodunu döndürdüğüne dikkat edin. Yazdığımız metot, sunucudan dönen yeni oluşturulmuş nesneyi (genellikle sunucu tarafından atanan benzersiz bir ID ile birlikte) tekrar PostModel nesnesine dönüştürerek arayüze geri verir. Bu sayede arayüz, işlemin başarıyla tamamlandığını doğrulamış olur.

Adım 5: Dio Interceptor (Kesici) Kullanımı ve Güvenlik Önlemleri

Büyük ölçekli uygulamalarda, her API isteğinde tekrar eden işlemler bulunur. Örneğin; her isteğe yetkilendirme jetonu (Bearer Token) eklemek, gelen yanıtları loglamak veya yetkisiz işlem (HTTP 401 Unauthorized) durumunda kullanıcıyı otomatik olarak giriş ekranına yönlendirmek gibi. Dio kütüphanesinin sunduğu Interceptor (Kesici) mekanizması, bu işlemleri merkezi bir noktadan yönetmemizi sağlar.

Aşağıdaki kod örneğinde, her giden isteğin başına otomatik olarak "Bearer Token" ekleyen ve gelen yanıtları konsola yazdıran özel bir Interceptor sınıfının nasıl yazılacağı ve Dio istemcisine nasıl entegre edileceği gösterilmiştir:

import 'package:dio/dio.dart';

class CustomInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    // Gerçek uygulamalarda bu token güvenli depolama alanından (flutter_secure_storage) okunmalıdır
    const String secureToken = "2026_yapay_zeka_ve_mobil_token_ornek_deger";
    
    // Her giden isteğin başlığına (Header) Authorization ekleniyor
    options.headers['Authorization'] = 'Bearer $secureToken';
    
    print('--- İSTEK GÖNDERİLİYOR ---');
    print('Yol: ${options.path}');
    print('Metot: ${options.method}');
    
    return super.onRequest(options, handler);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    print('--- YANIT ALINDI ---');
    print('Durum Kodu: ${response.statusCode}');
    
    return super.onResponse(response, handler);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    print('--- HATA OLUŞTU ---');
    print('Hata Mesajı: ${err.message}');
    
    return super.onError(err, handler);
  }
}

// Bu interceptor'ı servis sınıfımızdaki dio nesnesine şu şekilde ekleriz:
// _dio.interceptors.add(CustomInterceptor());

Interceptor kullanımı, kod tekrarını önler ve güvenlik politikalarının tek bir merkezden uygulanmasını garanti eder. Özellikle hassas verilerle çalışırken, tüm ağ trafiğini bu kesiciler üzerinden denetlemek güvenlik açıklarını asgariye indirir.

Kritik Güvenlik Uyarısı: API anahtarlarını, şifreleri veya özel jetonları (Access Tokens) asla kaynak kodunuzun içinde düz metin (hardcoded) olarak saklamayın. Bu verileri cihaz üzerinde saklamanız gerekiyorsa flutter_secure_storage gibi şifreli yerel veri tabanlarını kullanın. Hassas API anahtarlarını ise derleme aşamasında --dart-define veya .env dosyaları aracılığıyla uygulamaya güvenli bir şekilde enjekte edin.

Ağ İsteklerinde Hata Yönetimi ve Gelişmiş Retry (Yeniden Deneme) Mekanizması

Mobil uygulamalarda ağ bağlantısı her zaman kararlı olmayabilir. Tünellerden geçerken yaşanan anlık sinyal kayıpları