izmir-open-data-java-v1.0.0

İzmir Open Data · Java SDK

İzmir Büyükşehir Belediyesi Açık Veri Portalı ve Open API servisleri için modern, asenkron ve tip güvenli (Java 17 Records) Enterprise Java İstemcisi.

---

🚀 Özellikler

• Tam Asenkron Destek: OkHttp3 altyapısı ve CompletableFuture mimarisi ile non-blocking, yüksek performanslı istekler.
• %100 Tip Güvenliği: API yanıtları Java 17 record yapılarına (Immutable POJO) dönüştürülür. Lombok bağımlılığı olmadan temiz ve güvenli veri modelleri.
• Kapsamlı Servis Desteği: ESHOT, İZBAN, Metro, Vapur, BİSİM, İZSU, Otopark, Etkinlikler ve daha fazlası dahil 30 farklı servis ve 100'den fazla endpoint desteği. (Tüm servislerin tam listesini incelemek için Servisler Listesi (docs/SERVICES.md) dokümanına göz atın.)
• Dependency Injection (DI) Uyumu: Spring Boot ve diğer popüler Java framework'leri ile "Constructor Injection" uyumlu Facade yapısı.
• Gelişmiş Hata Yönetimi: HTTP, Network ve JSON hatalarını yöneten temiz, Unchecked Custom Exception (IzmirApiException, IzmirNetworkException) hiyerarşisi.
• Test Edilmiş Altyapı: MockWebServer kullanılarak otomatize edilmiş JUnit 5 testleri ile %100 rotalama ve HTTP coverage oranı.

📦 Kurulum

Proje standart Gradle Kotlin DSL ile yapılandırılmıştır. Kendi projene modül olarak ekleyebilir veya kaynak koddan derleyebilirsin:

# Repoyu klonlayın
git clone https://github.com/AtaCanYmc/izmir-open-data-java.git
cd izmir-open-data-java

# Gradle ile build alın ve testleri çalıştırın
./gradlew clean build

Eğer projeyi yerel Maven deponuza (Local Maven Repository) kurmak isterseniz:

./gradlew publishToMavenLocal

Daha sonra kendi Java/Spring Boot projenizin build.gradle (veya pom.xml) dosyasına ekleyebilirsiniz:

implementation("com.atacan.izmir.opendata:izmir-open-data-java:1.0.0-SNAPSHOT")

📖 Temel Kullanım

SDK, modern ve akıcı bir Builder desenine sahiptir.

import com.atacan.izmir.opendata.IzmirDataClient;
import com.atacan.izmir.opendata.IzmirDataClientBuilder;

public class Main {
    public static void main(String[] args) {
        
        // 1. Client'ı İnşa Et (Opsiyonel olarak timeout ve API Key verebilirsiniz)
        IzmirDataClient client = IzmirDataClientBuilder.builder()
                .apiKey("YOUR_API_KEY_HERE") // Gerekliyse
                .build();

        // 2. Senkron Kullanım Örneği (BİSİM)
        var istasyonlar = client.bisim().getIstasyonList();
        System.out.println("Toplam BİSİM İstasyonu: " + istasyonlar.kayitlar().size());

        // 3. Asenkron Kullanım Örneği (ESHOT)
        client.eshot().getHatlarAsync().thenAccept(hatlar -> {
            System.out.println("Asenkron Çekilen ESHOT Hatları: " + hatlar.size());
        }).exceptionally(ex -> {
            System.err.println("Hata oluştu: " + ex.getMessage());
            return null;
        });

        // 4. Farklı Servislere Erişim
        // client.metro()...
        // client.izsu()...
        // client.vapur()...
    }
}

🏗️ Mimari ve Tasarım (Docs)

Kütüphane kodlarının SOLID prensiplerine uygun olarak nasıl tasarlandığını inceleyebilirsiniz:

1. Facade Deseni: Kullanıcılar sadece IzmirDataClient arayüzü ile muhatap olur. Karmaşık HTTP istek motoru (ApiClient) ve alt servisler (eshot(), izsu()) arkada kapsüllenmiştir.
2. Immutable Modeller: Tüm veri taşıma objeleri (DTO'lar) Java 17 record olarak tanımlanmıştır. Bu sayede veriler değiştirilemez (Thread-Safe) ve öngörülebilir kalır.
3. Mock Testleri: Servislerin doğru URL ve HTTP metotlarına istek attığından emin olmak için her endpoint OkHttp MockWebServer ile test edilmiştir.

🧪 Testler ve Geliştirme

Projedeki tüm API çağrı yapıları (30 farklı servis) otomatik test edilmektedir.

# Tüm JUnit 5 testlerini çalıştır
./gradlew test

📄 Lisans

Bu proje Apache License 2.0 altında lisanslanmıştır. Daha fazla bilgi için LICENSE dosyasına bakabilirsiniz.