Client-Bibliotheken

Die REST-API ist schlichtes HTTP und JSON, und ein fetch-Aufruf ist ein völlig brauchbarer Weg, sie zu nutzen. Die Client-Bibliotheken gibt es für die Teile, die niemand gern zweimal schreibt: eine gedrosselte Anfrage korrekt zu wiederholen, ein wiederholtes Anlegen gefahrlos zu machen und einen Cursor bis ans Ende einer Liste zu verfolgen.

Drei Bibliotheken, ein Vertrag:

| Sprache | Paket | Quellcode | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

Installation

Die Pakete liegen noch nicht auf npm, PyPI oder Packagist. Die Veröffentlichung wartet auf die Registry-Konten; der Code ist vollständig und heute schon aus einem Checkout des Repositorys installierbar, und aus den Befehlen unten wird ein einzeiliges npm install @linkprofit/sdk (und seine Entsprechungen), sobald die Konten existieren.

Node, aus einem lokalen Checkout:

npm install /path/to/linkprofit/packages/sdk-node

Python, aus einem lokalen Checkout:

pip install /path/to/linkprofit/sdk/python

PHP, über ein Composer-Path-Repository in Ihrer composer.json:

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

Was alle drei gleich machen

Die Bibliotheken sind mit Absicht langweilig und mit Absicht gleich. Das Verhalten lernen Sie einmal, und es gilt in jeder Sprache.

Authentifizierung. Sie übergeben einen Workspace-Schlüssel (lp_live_…); der Client setzt bei jeder Anfrage den Authorization-Header. Die Basis-URL ist eine Option, derselbe Code läuft in Tests also auch gegen eine lokale Instanz. Berechtigungen und Schlüsselwechsel stehen unter Authentifizierung.

Wiederholungen, die den Server respektieren. Ein 429 oder ein vorübergehendes 5xx wird mit Backoff wiederholt, und Retry-After wird befolgt statt geraten — der Server weiß bereits, wann das Fenster wieder frei wird. Die Zahl der Versuche ist gedeckelt, und eine Anfrage, die aus eigenem Recht scheitert (validation_failed, conflict, not_found), wird nie wiederholt: Eine falsche Anfrage zu wiederholen verbraucht nur das Rate-Limit-Budget.

Idempotente Änderungen. Jeder verändernde Aufruf trägt einen Idempotency-Key, eine Wiederholung nach einem Netzwerk-Timeout liefert also die gespeicherte Antwort zurück, statt einen zweiten Link anzulegen. Sie können einen eigenen Schlüssel mitgeben — eine Bestellnummer, eine Job-ID —, wenn die Wiederholung aus einem anderen Prozess oder einem späteren Lauf kommen kann. Die Schlüssel werden 24 Stunden gespeichert; derselbe Schlüssel mit anderem Rumpf antwortet mit 409.

Cursor-Paginierung als Iterator. Listen-Endpunkte sind Cursor-paginiert, und die Clients machen daraus Iteratoren: Sie laufen über Links, der Client holt die nächste Seite, wenn die aktuelle zu Ende ist, und hört auf, sobald der Cursor null ist. Kein Rechnen mit Seiten, kein Risiko des Abzählfehlers, der stillschweigend einen Datensatz verschluckt.

Fehler als Ausnahmen. Fehlschläge lösen den natürlichen Fehlertyp der jeweiligen Sprache aus und tragen den API-code, die menschenlesbare Meldung und bei Validierungsfehlern die details je Feld. Verzweigen Sie über den Code, nicht über den Meldungstext — die Codes sind der dokumentierte Vertrag.

Die Anfrage- und Antworttypen des Node-Clients werden aus demselben OpenAPI-Dokument erzeugt, das auch die Referenz rendert — veröffentlicht unter /openapi.json —, die Typen können also nicht von der laufenden API abdriften. Die Clients für Python und PHP folgen demselben Dokument von Hand, in der Ausdrucksweise ihrer Sprache.

Schnellstart

Jedes Paket bringt eine README mit seinem vollständigen Umfang mit; die Schnipsel unten zeigen die Form, die alle drei teilen — einen Client mit einem Schlüssel bauen, die Ressourcengruppe aufrufen, ein typisiertes Objekt zurückbekommen.

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

Welche soll ich nehmen

• Node / TypeScript — der vollständigste Umfang, weil die Typen direkt aus dem OpenAPI-Dokument kommen. Die natürliche Wahl für ein JavaScript-Backend, eine Serverless-Funktion oder ein Build-Skript.
• Python — für Auswertungen und Datenarbeit: Analytics in ein Notebook, einen geplanten Job oder einen Dashboard-Feed ziehen.
• PHP — für die Welt der Content-Systeme. Ein WordPress-Plugin oder ein Laravel-Service, der Links kürzt, während Inhalte veröffentlicht werden.
• Keine davon — liegt Ihre Sprache anderswo, ist die API ganz gewöhnliches HTTP. Der Schnellstart beginnt mit curl, und alles, was die Clients tun (Wiederholungen, Idempotenz, Cursor), ist dokumentiertes Verhalten, das Sie in fünfzig Zeilen selbst bauen.

Was auch immer Sie wählen: Die API-Referenz ist die vollständige Liste der Endpunkte, Felder und Fehlercodes — die Bibliotheken sind eine Bequemlichkeit darüber, nie eine andere API.

Ebenfalls lesenswert

• Rate-Limits — das Budget, in dem die Wiederholungslogik arbeitet.
• Webhooks — Ereignisse zugestellt bekommen, statt sie abzufragen.
• MCP-Server — dieselben Operationen aus einem KI-Assistenten heraus.