Yapılandırma

listingsapi-js istemcisini yapılandırın: API anahtarının belirlenmesi, temel URL'nin değiştirilmesi, zaman aşımları ve otomatik yeniden denemeler.

Kurucu seçenekleri

ListingsAPI, tüm alanları isteğe bağlı olan tek bir seçenek nesnesi kabul eder:

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // Every default spelled out:const custom = new ListingsAPI({apiKey: process.env.LISTINGSAPI_KEY,baseUrl: 'https://listingsapi.com',timeout: 240000,   // 4 minutes per attemptmaxRetries: 2,     // up to 3 attempts total});

API anahtarının belirlenmesi

Anahtarı asla kaynak koduna sabit olarak yazmayın. Argümansız kurucu, LISTINGSAPI_KEY değerini ortamdan okur:

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Veya bir gizli bilgi yöneticisinden aldığınız anahtarı iletin:

import { getSecret } from './secrets.js'; const apiKey = await getSecret('LISTINGSAPI_KEY');const client = new ListingsAPI({ apiKey });

Her iki yerde de anahtar bulunamazsa kurucu, herhangi bir istek yapılmadan önce hemen AuthenticationError hatası fırlatır.

Temel URL'yi değiştirme

İstemciyi dahili bir proxy'ye veya hazırlık ortamına yönlendirin:

const client = new ListingsAPI({baseUrl: 'https://listings-proxy.internal.example.com',});

Sondaki eğik çizgiler otomatik olarak kaldırılır; bu nedenle 'https://listingsapi.com/' ve 'https://listingsapi.com' aynı şekilde davranır.

Zaman aşımları

Her deneme dahili olarak AbortSignal.timeout(timeout) ile sarmalanır (Node 18+), bu nedenle SDK çağrıları için kendi AbortController yapınızı kullanmanız gerekmez. Varsayılan süre, deneme başına 240000 ms'dir (4 dakika).

Zaman aşımına uğrayan bir deneme, bağlantı hatası olarak sayılır: istemci, deneme hakkı kaldığı sürece işlemi yeniden dener ve son deneme de başarısız olursa APIConnectionError hatası fırlatılır. Gecikmeye duyarlı kod yolları için zaman aşımı süresini azaltın:

const client = new ListingsAPI({ timeout: 15000 }); // 15 s per attempt

Otomatik yeniden denemeler

İstemci, 429, 500, 502, 503 ve 504 durum kodlu yanıtlar ile ağ düzeyindeki hatalar (DNS hataları, reddedilen bağlantılar, zaman aşımları) için yalnızca güvenli yöntemlerde yeniden deneme yapar: GET, HEAD ve OPTIONS. 0.3.2 itibarıyla bir yazma isteği (POST, DELETE) tam olarak bir kez gönderilir ve başarısızlık durumu hemen çağıran koda iletilir. Varsayılan maxRetries: 2 ayarıyla her okuma işlemi için en fazla 3 deneme yapılır.

v4 API, Idempotency-Key desteği sunmaz ve tekrarlanan yazma işlemlerini algılamaz; bu nedenle zaman aşımına uğrayan veya 5xx döndüren bir yazma işlemi zaten kaydedilmiş olabilir. Kontrol etmeden yeniden denemek ikinci bir konum, gönderi veya yorum yanıtı oluşturur. Bir yazma işlemini tekrarlamadan önce, kontrolünüzdeki bir anahtarı kullanarak kaydı yeniden okuyun.

Her yeniden denemeden önceki bekleme süresi:

1. Yanıtta pozitif bir saniye değeri içeren Retry-After başlığı varsa istemci tam olarak bu süre kadar bekler.
2. Aksi takdirde bekleme süresini üstel olarak artırır: ilk yeniden denemeden önce 500 ms bekler ve sonraki her yeniden denemede bu süreyi iki katına çıkarır (1 s, 2 s vb.).

Ağ hatalarında beklemeden hemen yeniden deneme yapılır. Deneme hakları tükendiğinde son yanıt, belirli bir türde hataya dönüştürülür (RateLimitError, InternalServerError ve benzerleri; bkz. Hata işleme); ağ hatası nedeniyle deneme hakları tükendiğinde ise APIConnectionError hatası fırlatılır.

// Fail fast and own the retry policy yourself:const client = new ListingsAPI({ maxRetries: 0 });

Konum kimlikleri

SDK'nin konum kimliği kabul ettiği her yerde sayısal kimlikler otomatik olarak API'nin base64 biçimine (Location:<id>) kodlanır; zaten kodlanmış kimlikler ise değiştirilmeden iletilir. Kodlanmış biçime doğrudan ihtiyaç duyarsanız yardımcı fonksiyon da dışa aktarılır:

import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // returned as-is

Başlık biçimi

Her isteğin kimlik doğrulaması şu şekilde yapılır:

Authorization: API <your-key>Content-Type: application/json

SDK, her çağrıda bu başlıkları otomatik olarak ayarlar. Bunları yapılandırmanız gerekmez.

TypeScript projesi kurulumu

SDK, öncelikle TypeScript için tasarlanmıştır ve tür tanımlarıyla birlikte gelir; bu nedenle ayrı bir @types paketi yüklemeniz gerekmez. Tekrarlanabilir derlemeler için sürümü sabitleyin:

npm install listingsapi-js@0.3.2

Node 18+ projesi için asgari bir tsconfig.json:

{"compilerOptions": {  "target": "ES2022",  "module": "Node16",  "moduleResolution": "Node16",  "strict": true,  "outDir": "dist"}}

package.json içinde "type": "module" bulunan ESM projelerinde "module": "Node16" ve "moduleResolution": "Node16" kullanın. CJS projelerinde "module": "CommonJS" ve "moduleResolution": "Node" sorunsuz çalışır; paket her iki derlemeyi de içerir ve CommonJS kodu paketi const { ListingsAPI } = require('listingsapi-js') ile yükler.

TypeScript olmadan kullanım

listingsapi-js, hiçbir çalışma zamanı bağımlılığı olmadan düz JavaScript'e derlenir. Derleme adımına gerek kalmadan bir .js veya .mjs dosyasından içe aktarabilirsiniz:

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();const page = await client.fetchAllLocations({ first: 5 });for (const location of page.locations) {console.log(location.name, location.city); // Acme Dental Midtown}

Sonraki adımlar

• Hızlı başlangıç, çalışan ilk betiğiniz
• Kullanım senaryoları, uçtan uca uygulama örnekleri
• Hata işleme, hata hiyerarşisi ve yeniden deneme yöntemleri