İ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

Kütüphane GitHub Packages üzerinde resmi olarak yayınlanmaktadır. Projenize eklemek için aşağıdaki adımları izleyebilirsiniz.

Gradle (Kotlin DSL)

build.gradle.kts dosyanıza GitHub Packages repository'sini ve bağımlılığı ekleyin:

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/AtaCanYmc/izmir-open-data-java")
        credentials {
            username = System.getenv("GITHUB_ACTOR") // Veya GitHub kullanıcı adınız
            password = System.getenv("GITHUB_TOKEN") // Veya Personal Access Token (read:packages yetkisine sahip)
        }
    }
}

dependencies {
    implementation("com.atacan.izmir.opendata:izmir-open-data-java:1.0.0") // En güncel sürümü kullanın
}

Maven

pom.xml dosyanıza repository ve dependency tanımlarını ekleyin:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/AtaCanYmc/izmir-open-data-java</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.atacan.izmir.opendata</groupId>
        <artifactId>izmir-open-data-java</artifactId>
        <version>1.0.0</version> <!-- En güncel sürümü kullanın -->
    </dependency>
</dependencies>

Not: GitHub Packages'dan kütüphane indirebilmek için Maven veya Gradle ortamınıza GitHub kimlik bilgilerinizi tanımlamanız gerekmektedir.

Eğer kaynak koddan derleyip yerel (local) ortamda kurmak isterseniz:

git clone https://github.com/AtaCanYmc/izmir-open-data-java.git
cd izmir-open-data-java
./gradlew publishToMavenLocal

📖 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.