Konfigurasi

Konfigurasikan klien listingsapi-js: penentuan kunci API, penggantian URL dasar, batas waktu, dan percobaan ulang otomatis.

Opsi konstruktor

ListingsAPI menerima satu objek opsi yang sepenuhnya opsional:

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});

Penentuan kunci API

Jangan pernah menuliskan kunci secara langsung di kode sumber. Konstruktor tanpa argumen membaca LISTINGSAPI_KEY dari lingkungan:

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Atau berikan kunci yang Anda ambil dari pengelola rahasia:

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

Jika kunci tidak ditemukan di kedua tempat tersebut, konstruktor langsung melempar AuthenticationError, sebelum permintaan apa pun dibuat.

Penggantian URL dasar

Arahkan klien ke proxy internal atau lingkungan staging:

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

Garis miring di akhir dihapus secara otomatis, sehingga 'https://listingsapi.com/' dan 'https://listingsapi.com' berperilaku sama.

Batas waktu

Setiap percobaan dibungkus dengan AbortSignal.timeout(timeout) secara internal (Node 18+), sehingga Anda tidak perlu membungkus pemanggilan SDK dengan AbortController sendiri. Batas waktu bawaan adalah 240000 ms (4 menit) per percobaan.

Percobaan yang melewati batas waktu dianggap sebagai kegagalan koneksi: klien mencobanya ulang selama masih ada sisa percobaan, dan kegagalan terakhir melempar APIConnectionError. Kurangi batas waktu untuk jalur eksekusi yang sensitif terhadap latensi:

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

Percobaan ulang otomatis

Klien mencoba ulang permintaan yang mendapat respons berstatus 429, 500, 502, 503, dan 504, serta yang mengalami kegagalan pada tingkat jaringan (kesalahan DNS, koneksi ditolak, batas waktu terlampaui), hanya untuk metode yang aman: GET, HEAD, dan OPTIONS. Mulai 0.3.2, operasi tulis (POST, DELETE) dikirim tepat satu kali dan kegagalannya langsung diteruskan ke pemanggil. Dengan pengaturan bawaan maxRetries: 2, setiap operasi baca melakukan hingga 3 percobaan.

API v4 tidak mendukung Idempotency-Key dan tidak mendeteksi operasi tulis yang berulang, sehingga operasi tulis yang melewati batas waktu atau mengembalikan 5xx mungkin sudah tersimpan. Mencobanya ulang tanpa pemeriksaan akan membuat lokasi, postingan, atau balasan ulasan kedua. Baca kembali rekaman menggunakan kunci yang Anda kendalikan sebelum mengulangi operasi tulis.

Jeda sebelum setiap percobaan ulang:

1. Jika respons menyertakan header Retry-After dengan jumlah detik positif, klien menunggu tepat selama durasi tersebut.
2. Jika tidak, jeda bertambah secara eksponensial: 500 ms sebelum percobaan ulang pertama, lalu berlipat dua untuk setiap percobaan ulang berikutnya (1 dtk, 2 dtk, dan seterusnya).

Permintaan yang mengalami kegagalan jaringan langsung dicoba ulang, tanpa jeda. Setelah jatah percobaan habis, respons terakhir menjadi kesalahan dengan tipe tertentu (RateLimitError, InternalServerError, dan lainnya; lihat Penanganan kesalahan), dan kegagalan jaringan yang jatah percobaan ulangnya habis akan melempar APIConnectionError.

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

ID lokasi

Di setiap bagian SDK yang menerima ID lokasi, ID numerik secara otomatis dikodekan ke bentuk base64 API (Location:<id>), dan ID yang sudah dikodekan diteruskan tanpa perubahan. Fungsi pembantu ini diekspor jika Anda memerlukan bentuk yang dikodekan tersebut:

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

Format header

Setiap permintaan diautentikasi dengan:

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

SDK mengatur header ini secara otomatis pada setiap pemanggilan. Anda tidak perlu mengonfigurasinya.

Penyiapan proyek TypeScript

SDK dirancang terutama untuk TypeScript dan menyertakan definisi tipe, sehingga tidak ada paket @types terpisah yang perlu diinstal. Tetapkan versi tertentu agar hasil build dapat direproduksi:

npm install listingsapi-js@0.3.2

tsconfig.json minimal untuk proyek Node 18+:

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

Untuk proyek ESM dengan "type": "module" di package.json, gunakan "module": "Node16" dan "moduleResolution": "Node16". Untuk proyek CJS, "module": "CommonJS" dan "moduleResolution": "Node" berfungsi dengan baik; paket ini menyertakan kedua build, dan kode CommonJS memuatnya dengan const { ListingsAPI } = require('listingsapi-js').

Menggunakan tanpa TypeScript

listingsapi-js dikompilasi menjadi JavaScript biasa tanpa dependensi runtime. Anda dapat mengimpornya dari file .js atau .mjs tanpa langkah build:

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}

Langkah berikutnya

• Panduan memulai, skrip pertama Anda yang berfungsi
• Kasus penggunaan, panduan implementasi dari awal hingga akhir
• Penanganan error, hierarki error dan pola percobaan ulang