Konfiguration

listingsapi-js-Client konfigurieren: API-Schlüssel ermitteln, Basis-URL überschreiben, Zeitlimits und automatische Wiederholungsversuche.

Konstruktoroptionen

ListingsAPI akzeptiert ein einzelnes, vollständig optionales Optionsobjekt:

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

Ermittlung des API-Schlüssels

Hinterlegen Sie den Schlüssel niemals fest im Quellcode. Der Konstruktor ohne Argumente liest LISTINGSAPI_KEY aus der Umgebung:

export LISTINGSAPI_KEY="your-api-key"

const client = new ListingsAPI();

Alternativ können Sie einen Schlüssel übergeben, den Sie aus einer Geheimnisverwaltung abgerufen haben:

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

Wenn an keiner der beiden Stellen ein Schlüssel gefunden wird, löst der Konstruktor sofort AuthenticationError aus, bevor eine Anfrage gesendet wird.

Basis-URL überschreiben

Richten Sie den Client auf einen internen Proxy oder eine Staging-Umgebung aus:

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

Abschließende Schrägstriche werden automatisch entfernt, sodass sich 'https://listingsapi.com/' und 'https://listingsapi.com' gleich verhalten.

Zeitlimits

Jeder Versuch wird intern mit AbortSignal.timeout(timeout) ausgeführt (Node 18+), sodass Sie für SDK-Aufrufe keinen eigenen AbortController benötigen. Der Standardwert beträgt 240000 ms (4 Minuten) pro Versuch.

Ein Versuch, dessen Zeitlimit überschritten wurde, zählt als Verbindungsfehler: Der Client wiederholt ihn, solange noch Versuche verbleiben, und löst beim endgültigen Fehlschlag APIConnectionError aus. Verringern Sie das Zeitlimit für latenzempfindliche Codepfade:

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

Automatische Wiederholungsversuche

Der Client wiederholt Anfragen bei Antworten mit dem Status 429, 500, 502, 503 und 504 sowie bei Fehlern auf Netzwerkebene (DNS-Fehler, abgelehnte Verbindungen, Zeitüberschreitungen), jedoch nur für die sicheren Methoden: GET, HEAD und OPTIONS. Ab 0.3.2 wird ein Schreibzugriff (POST, DELETE) genau einmal gesendet und ein Fehlschlag sofort gemeldet. Mit dem Standardwert maxRetries: 2 werden für jeden Lesezugriff bis zu 3 Versuche unternommen.

Die v4-API unterstützt Idempotency-Key nicht und erkennt keine wiederholten Schreibzugriffe, sodass ein Schreibzugriff, dessen Zeitlimit überschritten wird oder der 5xx zurückgibt, möglicherweise bereits dauerhaft gespeichert wurde. Ein ungeprüfter Wiederholungsversuch würde einen zweiten Standort, einen zweiten Beitrag oder eine zweite Antwort auf eine Bewertung erstellen. Lesen Sie den Datensatz anhand eines von Ihnen kontrollierten Schlüssels erneut aus, bevor Sie einen Schreibzugriff wiederholen.

Die Wartezeit vor jedem Wiederholungsversuch:

1. Wenn die Antwort einen Retry-After-Header mit einer positiven Anzahl von Sekunden enthält, wartet der Client genau so lange.
2. Andernfalls erhöht sich die Wartezeit exponentiell: 500 ms vor dem ersten Wiederholungsversuch, danach verdoppelt sie sich mit jedem weiteren Wiederholungsversuch (1 s, 2 s und so weiter).

Bei Netzwerkfehlern erfolgt der Wiederholungsversuch sofort, ohne Wartezeit. Sobald keine Versuche mehr verbleiben, wird die letzte Antwort in einen typisierten Fehler umgewandelt (RateLimitError, InternalServerError und weitere; siehe Fehlerbehandlung), und bei einem Netzwerkfehler wird nach Ausschöpfen aller Versuche APIConnectionError ausgelöst.

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

Standort-IDs

Überall dort, wo das SDK eine Standort-ID entgegennimmt, werden numerische IDs automatisch in das Base64-Format der API (Location:<id>) kodiert, und bereits kodierte IDs werden unverändert weitergegeben. Die Hilfsfunktion wird exportiert, falls Sie die kodierte Form selbst benötigen:

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

Header-Format

Jede Anfrage wird wie folgt authentifiziert:

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

Das SDK setzt diese Header bei jedem Aufruf automatisch. Sie müssen sie nicht konfigurieren.

TypeScript-Projekt einrichten

Das SDK ist vorrangig für TypeScript ausgelegt und enthält bereits Typdefinitionen, sodass kein separates @types-Paket installiert werden muss. Legen Sie die Version für reproduzierbare Builds fest:

npm install listingsapi-js@0.3.2

Eine minimale tsconfig.json für ein Projekt mit Node 18+:

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

Verwenden Sie für ESM-Projekte mit "type": "module" in package.json die Einstellungen "module": "Node16" und "moduleResolution": "Node16". Für CJS-Projekte eignen sich "module": "CommonJS" und "moduleResolution": "Node"; das Paket enthält beide Builds, und CommonJS-Code lädt es mit const { ListingsAPI } = require('listingsapi-js').

Verwendung ohne TypeScript

listingsapi-js wird zu reinem JavaScript ohne Laufzeitabhängigkeiten kompiliert. Sie können es ohne Build-Schritt aus einer .js- oder .mjs-Datei importieren:

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}

Nächste Schritte

• Schnellstart, Ihr erstes funktionsfähiges Skript
• Anwendungsfälle, vollständige Anleitungen
• Fehlerbehandlung, die Fehlerhierarchie und Muster für Wiederholungsversuche