Librerie client

L'API REST è semplice HTTP e JSON, e una chiamata fetch è un modo perfettamente valido per usarla. Le librerie client esistono per le parti che nessuno ha voglia di scrivere due volte: ripetere correttamente una richiesta respinta dal limite di frequenza, rendere sicura la ripetizione di una creazione e percorrere un cursore fino in fondo a un elenco.

Tre librerie, un unico contratto:

| Linguaggio | Pacchetto | Sorgente | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

Installazione

I pacchetti non sono ancora su npm, PyPI o Packagist. La pubblicazione attende gli account sui registri; il codice è completo e già oggi si installa da una copia locale del repository, e i comandi qui sotto diventeranno un npm install @linkprofit/sdk su una sola riga (e i suoi equivalenti) non appena gli account esisteranno.

Node, da una copia locale:

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

Python, da una copia locale:

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

PHP, tramite un repository Composer di tipo path nel tuo composer.json:

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

Ciò che tutte e tre fanno allo stesso modo

Le librerie sono deliberatamente noiose e deliberatamente simili tra loro. Impari il comportamento una volta sola e vale in ogni linguaggio.

Autenticazione. Passi una chiave di area di lavoro (lp_live_…); il client imposta l'header Authorization su ogni richiesta. L'URL di base è un'opzione, così lo stesso codice può girare contro un'istanza locale nei test. Vedi Autenticazione per ambiti e rotazione.

Nuovi tentativi che rispettano il server. Un 429 o un 5xx temporaneo viene ripetuto con backoff, e Retry-After viene rispettato invece che indovinato — il server sa già quando la finestra si libera. Il numero di tentativi ha un tetto, e una richiesta che fallisce nel merito (validation_failed, conflict, not_found) non viene mai ripetuta: ripetere una richiesta sbagliata spreca soltanto il budget del limite di frequenza.

Scritture idempotenti. Ogni chiamata che modifica dati porta con sé un Idempotency-Key, così un nuovo tentativo dopo un timeout di rete restituisce la risposta già salvata invece di creare un secondo link. Puoi fornire una chiave tua — l'id di un ordine, l'id di un job — quando il nuovo tentativo può arrivare da un altro processo o da un'esecuzione successiva. Le chiavi vivono 24 ore; la stessa chiave con un corpo diverso risponde 409.

Paginazione a cursore come iteratore. Gli endpoint di elenco sono paginati a cursore e i client li espongono come iteratori: tu cicli sui link, il client richiede la pagina successiva quando quella corrente si esaurisce e si ferma quando il cursore è null. Nessuna aritmetica delle pagine, nessun rischio di quell'errore di uno che fa sparire una riga in silenzio.

Errori come eccezioni. I fallimenti sollevano il tipo di errore naturale del linguaggio, che porta con sé il code dell'API, il messaggio per le persone e, per gli errori di validazione, i details campo per campo. Ramifica sul codice, non sul testo del messaggio — sono i codici il contratto documentato.

I tipi di richiesta e di risposta del client Node sono generati dallo stesso documento OpenAPI che il riferimento rende — pubblicato su /openapi.json — quindi i tipi non possono divergere dall'API in esecuzione. I client Python e PHP seguono lo stesso documento a mano, nell'idioma del loro linguaggio.

Guida rapida

Ogni pacchetto include un README con la sua superficie completa; gli snippet qui sotto mostrano la forma comune a tutti e tre — costruisci un client con una chiave, chiami il gruppo di risorse, ricevi indietro un oggetto tipizzato.

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'];

Quale scegliere

• Node / TypeScript — la superficie più completa, perché i suoi tipi arrivano direttamente dal documento OpenAPI. La scelta naturale per un backend JavaScript, una funzione serverless o uno script di build.
• Python — per la reportistica e il lavoro sui dati: porta l'analytics dentro un notebook, un job pianificato o l'alimentazione di una dashboard.
• PHP — per il mondo dei CMS. Un plugin WordPress o un servizio Laravel che accorcia i link man mano che i contenuti vengono pubblicati.
• Nessuna delle tre — se il tuo linguaggio è un altro, l'API è normale HTTP. La guida rapida parte da curl, e tutto ciò che fanno i client (nuovi tentativi, idempotenza, cursori) è comportamento documentato che puoi implementare in cinquanta righe.

Qualunque cosa tu scelga, il riferimento dell'API è l'elenco completo di endpoint, campi e codici di errore — le librerie sono una comodità che gli sta sopra, mai un'API diversa.

Vale la pena leggere anche

• Limiti di frequenza — il budget dentro cui lavora la logica dei nuovi tentativi.
• Webhook — ricevi gli eventi in push invece di fare polling.
• Server MCP — le stesse operazioni da un assistente AI.