GraphQL'e Giriş

v3, KartFiyat'ın GraphQL API'sidir. Tek bir uç noktaya sorgu gönderir, yalnızca ihtiyacınız olan veriyi istersiniz.

Herkese açık API

v1 (REST) ve v3 (GraphQL) ikisi de herkese açıktır. Aynı API anahtarı iki sürümde de çalışır; kullanım limitleri (rate limiting) birlikte değil, her sürüm için ayrı ayrı sayılır. Pazar fiyatları (PriceCharting, TCGMarket, CardMarket) ve kart veri alanları yalnızca Profesyonel plan ve üzerinde döner.

Uç Nokta

Tüm sorgu ve mutasyonlar aynı uç noktaya POST ile gönderilir:

https://kartfiyat.com/api/v3/graphql

Neden GraphQL?

İhtiyacın kadar veri: Yanıtta hangi alanların döneceğini sen seçersin; fazla veri indirmezsin.
Tek istek, çok kaynak: Kategori ve ürün bilgisini tek sorguda birlikte alabilirsin.
Kendi kendini belgeleyen şema: Şema sayfası tüm türleri, alanları ve argümanları gösterir.
Versiyonsuz alan seçimi: Alan eklemek kırıcı (breaking) değişiklik yaratmaz; eski istemciler aynı sorguyu çalıştırmaya devam eder.

İlk Sorgunuz

Aşağıdaki sorgu tüm kategorilerin adını ve slug'ını getirir:

query {
  categories {
    nodes {
      id
      name
      slug
    }
  }
}

cURL ile aynı istek:

curl -X POST "https://kartfiyat.com/api/v3/graphql" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ categories { nodes { id name slug } } }" }'

Yanıt

{
  "data": {
    "categories": {
      "nodes": [
        { "id": 1, "name": "Pokemon TCG", "slug": "pokemon-tcg" },
        { "id": 2, "name": "One Piece", "slug": "one-piece" }
      ]
    }
  }
}

Sorgu mu, Mutasyon mu?

Veri okuma işlemleri query, veri değiştirme (ekleme, güncelleme, silme) işlemleri mutation bloklarında yapılır. POST her ikisinde de kullanılır.

Argümanlar ve Filtreleme

Sorgular, alanlarınıza (argüman: değer) ekleyerek filtre ve sayfalama yapmanızı sağlar:

query {
  items(game: "pokemon", search: "charizard", first: 10) {
    nodes {
      name
      code
      prices { label price }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Sonraki Adımlar

Sorgular — kategoriler ve ürünler için örnekler
Mutasyonlar — veri değiştiren işlemler
Şema — tüm türler ve alanlar
Kimlik Doğrulama — anahtar kullanımı