L’API di LinkHarbor in sintesi

Con l’API REST controlli LinkHarbor dai tuoi programmi: crei pagine e link, modifichi e pubblichi bozze, generi link brevi o importi le statistiche nei tuoi report. Questo articolo è pensato per sviluppatori e spiega le regole di base valide per ogni endpoint.

#Quale strada fa per te?

#URL di base e versioni

URL di base

https://dock.at-harbor.com – tutti gli endpoint del prodotto si trovano sotto /v1, per esempio https://dock.at-harbor.com/v1/pages.

Versione

Al momento esiste solo la versione v1. Il numero di versione fa parte del percorso.

Protocollo

Solo HTTPS.

OpenAPI

La descrizione leggibile dalle macchine (OpenAPI 3.1) si trova su https://dock.at-harbor.com/openapi.yaml. Puoi caricarla in Postman, Insomnia o in un generatore di codice.

#Fare test nella sandbox

Per sviluppo e test esiste una sandbox separata. Si comporta come l’API reale, ma ne è completamente separata: account propri, dati propri, e nulla finisce nel tuo workspace reale.

API

https://drydock.at-harbor.com, con gli stessi percorsi di sopra, per esempio https://drydock.at-harbor.com/v1/pages.

Dashboard

https://sandbox-deck.linkharbor.com, per esempio per creare chiavi API.

Pagine

Le pagine pubblicate compaiono su https://<handle>.sandbox.linkharbor.com.

Account

Il tuo vero account LinkHarbor lì non funziona. Crea un account separato per la sandbox.

La sandbox non invia e-mail. Se ti registri tramite l’API (POST /v1/auth/register), il codice di verifica torna direttamente nella risposta, nel campo _dev_verification. Lo stesso vale per il ripristino della password e il cambio dell’e-mail. Questo campo esiste solo nella sandbox, quindi non farci affidamento nel tuo codice.

• Le notifiche push sono disattivate
• I pagamenti passano dalla modalità test di Stripe, non si muove denaro reale
• I limiti di richieste sono circa un terzo dei valori reali e i nuovi account sono limitati a 5 all’ora per indirizzo IP
• Il 1° di ogni mese alle 3:00 UTC la sandbox viene svuotata completamente e in seguito tutti gli account e i dati sono spariti
• Ogni risposta contiene l’header X-Environment: sandbox

#L’autenticazione in breve

1. Come proprietario o admin, crea nella dashboard sotto «Callback e API» una chiave API con gli scope che ti servono (da Creator Pro)
2. Scambia l’ID e il secret della chiave con un token di accesso tramite POST /v1/token
3. Invia il token con ogni richiesta nell’header Authorization: Bearer …
4. Dopo 15 minuti richiedi un nuovo token

Tutti i dettagli sono in Chiavi API e token di accesso, le autorizzazioni in Scope.

#Richieste e risposte

Formato

Richieste e risposte sono in JSON con codifica UTF-8. Per il caricamento dei file si usa anche multipart/form-data.

Content-Type

Invia l’header Content-Type: application/json con ogni richiesta che ha un corpo. Qualsiasi altro tipo viene rifiutato con 400 bad_request – compreso quello che curl imposta automaticamente con -d quando questo header manca.

Campi sconosciuti

I campi che un endpoint non conosce portano a 422 validation_failed. La risposta indica i campi sconosciuti.

JSON non valido

Porta a 400 invalid_json.

Dimensione

A seconda dell’endpoint, un corpo può essere al massimo di 64 KB, 1 MB o 2 MB, e un file caricato di 10 MB. Se è più grande, l’API risponde con 413 request_too_large. Tutti i limiti sono elencati in Limiti di richieste.

Elenchi

Arrivano come oggetto con il campo items, per esempio {"items":[…]}.

Creazione

Risponde con HTTP 201 e il nuovo ID, per esempio {"id":123}.

Azioni senza valore di ritorno

Rispondono con {"ok":true}.

Errori

Hanno sempre un formato fisso con un codice leggibile dalle macchine. Vedi Formato degli errori e codici di errore API.

#Paginazione

Non esiste un unico schema di paginazione. La maggior parte degli elenchi è piccola e torna completa; solo alcuni endpoint hanno parametri:

Per sort sui link brevi ci sono created_desc, created_asc, redirects_desc e redirects_asc; q cerca in slug, titolo e URL di destinazione (fino a 100 caratteri, senza distinzione tra maiuscole e minuscole). Per le statistiche, period accetta 24h, 7d, 30d, 90d, this_month, last_month, last_30d e custom; in alternativa passi from e to. granularity è hour o day.

#ID della richiesta e lingua

• Ogni risposta contiene l’header X-Request-Id – indicalo quando contatti l’assistenza
• Se invii tu stesso un header X-Request-Id, l’API usa quello
• Il testo dell’errore in message è nella lingua dell’account del proprietario del workspace, altrimenti segue Accept-Language; il codice in error resta sempre lo stesso

#Chiamarla dal browser?

Tecnicamente l’API consente chiamate dal browser (CORS). Ma un secret di chiave non deve mai stare in codice che gira dal lato del visitatore – né in un sito web né in un’app. Chiama sempre l’API dal tuo server.

#Piani

Non esiste una quota di chiamate API per piano. Valgono solo i limiti di richieste al minuto. I limiti di contenuto del tuo piano – come pagine, link o blocchi per pagina – valgono tramite l’API esattamente come nella dashboard. Vedi Piani a confronto.

#La tua prima chiamata

# Scambia la chiave con un token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Elenca le pagine (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Un esempio completo che aggiunge un link, cambia il design e pubblica si trova in Aggiornare una pagina tramite l’API.