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

importcom.atacan.izmir.opendata.IzmirDataClient;
importcom.atacan.izmir.opendata.IzmirDataClientBuilder;
publicclassMain {
publicstaticvoidmain(String[] args) {
// 1. Client'ı İnşa Et (Opsiyonel olarak timeout ve API Key verebilirsiniz)IzmirDataClientclient = IzmirDataClientBuilder.builder()
.apiKey("YOUR_API_KEY_HERE") // Gerekliyse
.build();
// 2. Senkron Kullanım Örneği (BİSİM)varistasyonlar = 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());
returnnull;
});
// 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.