API pubblica dei contenuti

L'API pubblica dei contenuti ti offre accesso programmatico in sola lettura ai post del blog nella tua organizzazione Nolorem. Usala per importare i contenuti in un sito Drupal, un front end personalizzato, un'app mobile o qualsiasi sistema esterno che abbia bisogno dei dati del tuo blog.

L'API è disponibile sul piano Premium. Tutto l'accesso è in sola lettura; la pubblicazione e la modifica restano all'interno di Nolorem.

Creare una chiave API

Solo gli amministratori dell'organizzazione possono creare chiavi API.

1. In Impostazioni, scorri fino alla sezione API Keys (visibile solo agli amministratori).
2. Clicca su Create API key.
3. Inserisci un nome descrittivo per la chiave (ad esempio, "Sito Drupal" o "Script di sincronizzazione contenuti").
4. Scegli l'ambito della chiave (vedi sotto).
5. Copia la chiave mostrata sullo schermo. Inizia con nlr_live_.

La chiave viene mostrata una sola volta. Conservala immediatamente in un gestore di segreti o in una variabile d'ambiente. Se la perdi, revoca la chiave e creane una nuova.

Scegliere l'ambito di una chiave

Quando crei una chiave, scegli se copre un blog specifico o tutti i blog della tua organizzazione.

Chiave con ambito su un blog (consigliata): la chiave è vincolata a un singolo blog. Può accedere solo a post, categorie e tag di quel blog. Se la chiave viene mai divulgata o condivisa, viene esposto solo il contenuto di quel singolo blog.

Chiave con ambito sull'intera organizzazione: la chiave ha accesso a tutti i blog della tua organizzazione. Usala solo quando hai un motivo deliberato per accedere a più blog con una singola chiave.

Il badge di ambito su ogni chiave nell'elenco mostra a quale blog è vincolata la chiave, oppure "Tutti i blog" per una chiave con ambito sull'intera organizzazione. L'ambito è fissato al momento della creazione. Per cambiare ambito, crea una nuova chiave con l'ambito desiderato, aggiorna eventuali consumatori, poi revoca la vecchia chiave.

Autenticare le richieste

Passa la chiave nell'header Authorization di ogni richiesta:

Authorization: Bearer nlr_live_your_key_here

Esempio con curl:

curl https://nolorem.io/api/v1/posts \
  -H "Authorization: Bearer nlr_live_your_key_here"

L'API è server-to-server. Non ci sono header CORS, quindi i client browser non possono chiamarla direttamente. Effettua tutte le chiamate API dal tuo back end o da uno script lato server.

Elencare i tuoi blog

GET /api/v1/blogs elenca i blog a cui la tua chiave può accedere. La forma della risposta è la stessa sia che la chiave abbia ambito su un blog sia sull'intera organizzazione.

curl https://nolorem.io/api/v1/blogs \
  -H "Authorization: Bearer nlr_live_your_key_here"

Risposta:

{
  "data": [
    { "id": "uuid", "slug": "my-blog", "name": "My Blog" },
    { "id": "uuid", "slug": "company-news", "name": "Company News" }
  ]
}

Una chiave con ambito su un blog restituisce esattamente una voce (il blog vincolato). Una chiave con ambito sull'intera organizzazione restituisce tutti i blog. Usa questo endpoint per scoprire quali blog copre una chiave prima di recuperare i contenuti.

Filtrare i post per blog

Tutti gli endpoint dei contenuti accettano un parametro blog opzionale. Passa l'UUID del blog o il suo slug:

# Filtra per slug
curl "https://nolorem.io/api/v1/posts?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Filtra per UUID
curl "https://nolorem.io/api/v1/posts?blog=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Se ometti blog, l'API restituisce i contenuti di tutti i blog a cui la tua chiave può accedere (il comportamento predefinito, non-breaking).

Se usi una chiave con ambito su un blog e passi ?blog= puntando a un blog diverso, l'API restituisce 403 Forbidden. Questo impedisce di indovinare quali blog esistono in un'organizzazione.

Lo stesso parametro blog funziona su /api/v1/categories e /api/v1/tags.

Elencare i post

GET /api/v1/posts restituisce un elenco paginato di post per i blog accessibili dalla tua chiave. Per impostazione predefinita restituisce i post pubblicati, 20 per pagina.

curl "https://nolorem.io/api/v1/posts?status=published&per_page=50" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Risposta:

{
  "data": [
    {
      "id": "uuid",
      "blog_id": "uuid",
      "title": "My blog post",
      "slug": "my-blog-post",
      "excerpt": "Lead paragraph...",
      "language": "en",
      "category": "Technology",
      "tags": ["AI", "Productivity"],
      "featured_image_url": "https://...",
      "published_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-10T14:30:00Z",
      "html": null
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 123 }
}

Il campo html è sempre null nelle risposte in elenco. Usa gli endpoint di dettaglio per ottenere il corpo completo del post.

Filtri disponibili

Parametro	Descrizione	Esempio
blog	UUID o slug del blog (predefinito: tutti i blog accessibili)	blog=my-blog
status	published, draft o scheduled (predefinito: published)	status=published
language	Codice lingua ISO 639-1	language=nl
category	Nome categoria (non distingue maiuscole/minuscole)	category=Technology
tag	Nome tag (non distingue maiuscole/minuscole)	tag=AI
updated_since	Data e ora ISO 8601; solo i post modificati dopo questa data	updated_since=2026-06-01T00:00:00Z
page	Numero di pagina, a partire da 1	page=2
per_page	Elementi per pagina, max 100	per_page=100

Recuperare un singolo post

Recupera un post tramite il suo UUID per ottenere il corpo HTML completo:

curl "https://nolorem.io/api/v1/posts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Oppure tramite il suo slug:

curl "https://nolorem.io/api/v1/posts/slug/my-blog-post" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Entrambi restituiscono un singolo oggetto PublicPost (non racchiuso in un array data) con il campo html popolato.

Sincronizzazione incrementale con updated_since

Per sincronizzare solo i contenuti nuovi o modificati, memorizza il timestamp dell'ultima sincronizzazione riuscita e passalo come updated_since all'esecuzione successiva:

# Sincronizzazione iniziale: recupera tutti i post pubblicati
curl "https://nolorem.io/api/v1/posts?per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Sincronizzazioni successive: solo i post modificati dall'ultima sincronizzazione
curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Scorri tutte le pagine dei risultati prima di memorizzare il nuovo timestamp di sincronizzazione.

Rilevare i post non pubblicati o eliminati

Quando usi updated_since per la sincronizzazione incrementale, la risposta predefinita restituisce solo i post ancora pubblicati. Se un post è stato spubblicato o eliminato in Nolorem dall'ultima sincronizzazione, semplicemente scompare dai risultati senza alcun segnale per rimuoverlo nella destinazione.

Per ottenere quel segnale, passa include_deleted=true insieme al tuo timestamp updated_since:

curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&include_deleted=true" \
  -H "Authorization: Bearer nlr_live_your_key_here"

La risposta include tutti i post attivi come al solito, più voci tombstone minimali aggiunte alla fine di data. Ogni tombstone ha:

• id: l'UUID del post che hai già da una sincronizzazione precedente
• status: lo stato attuale del post, oppure "deleted" se è stato rimosso definitivamente
• updated_at: quando è avvenuta la modifica
• deleted: true se il post è stato eliminato, false se è stato semplicemente spubblicato o spostato in bozza

{
  "data": [
    { "id": "...", "title": "Live post", "updated_at": "..." },
    { "id": "...", "status": "draft", "updated_at": "...", "deleted": false },
    { "id": "...", "status": "deleted", "updated_at": "...", "deleted": true }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "tombstones": 2 }
}

Usa meta.tombstones per sapere quante voci tombstone sono aggiunte. meta.total riflette sempre solo i post attivi.

Quando il tuo strumento di sincronizzazione vede un tombstone, spubblica o rimuovi la pagina corrispondente nella destinazione (ad esempio, imposta il nodo Drupal corrispondente su spubblicato o bozza).

Senza include_deleted=true, il comportamento è identico a quello precedente a questa modifica: vengono restituiti solo i post attivi e pubblicati.

Elencare categorie e tag

Due endpoint restituiscono la tassonomia completa di categorie e tag del tuo blog. Sono utili per gli strumenti esterni che devono mappare le categorie o i tag di Nolorem sulla propria tassonomia (ad esempio, un connettore Drupal che associa le categorie di Nolorem ai termini del vocabolario Drupal). Entrambi accettano il parametro blog.

# Tutte le categorie della tua organizzazione (o del blog vincolato)
curl "https://nolorem.io/api/v1/categories?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Tutti i tag della tua organizzazione (o del blog vincolato)
curl "https://nolorem.io/api/v1/tags?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Entrambi restituiscono l'elenco completo in una singola risposta (non paginata):

{ "data": [{ "id": "uuid", "name": "Marketing" }, { "id": "uuid", "name": "Technology" }] }

Si applicano lo stesso bearer token, lo stesso requisito del piano Premium e lo stesso ambito posts:read degli endpoint dei post.

Analisi di utilizzo per chiave

In Impostazioni, ogni riga di chiave può essere espansa per mostrare le analisi di utilizzo:

• Richieste (ultime 24h / totali): quante chiamate API ha effettuato questa chiave.
• Fonti distinte: quanti indirizzi IP e applicazioni client distinti hanno usato questa chiave di recente.
• Ultimo utilizzo: il timestamp della richiesta autenticata più recente.

Queste analisi ti aiutano a capire come vengono usate le tue chiavi e a individuare schemi inaspettati.

Segnalazione di condivisione della chiave

Se una chiave mostra un gran numero di indirizzi IP distinti in un breve periodo, Nolorem potrebbe segnalarla come "possibilmente condivisa o compromessa". La segnalazione appare come un avviso ambra sulla riga della chiave. La chiave continua a funzionare e non viene intrapresa alcuna azione automatica: si tratta di un segnale informativo.

Quando vedi la segnalazione, esamina i tuoi log di utilizzo. Se hai condiviso la chiave intenzionalmente (ad esempio, con più server in un cluster), valuta se lo schema di accesso è previsto. Se la chiave potrebbe essere stata divulgata o condivisa con parti non autorizzate, revocala e creane una nuova per limitare l'accesso.

Limiti di frequenza

Ogni chiave API è soggetta a questi limiti:

• 60 richieste al minuto
• 5.000 richieste al giorno

Quando superi un limite, l'API restituisce HTTP 429 con un header Retry-After che indica quanti secondi attendere prima di riprovare:

HTTP/1.1 429 Too Many Requests
Retry-After: 43

{ "error": "Rate limit exceeded" }

Implementa un backoff esponenziale per script di sincronizzazione affidabili e a lunga esecuzione.

Codici di errore

Stato	Significato
400	Parametri di query non validi
401	Chiave API mancante o non valida
403	Piano Premium richiesto, la chiave non ha l'ambito posts:read, oppure chiave con ambito su un blog usata con un valore ?blog= non corrispondente
404	Post non trovato
429	Limite di frequenza superato (controlla l'header Retry-After)

Specifica leggibile dalle macchine

La specifica API completa in formato OpenAPI 3.1 è disponibile all'indirizzo:

GET /api/v1/openapi.json

Questo endpoint non è autenticato. Puoi importarlo in Postman, Insomnia o qualsiasi strumento compatibile con OpenAPI.

Revocare una chiave

Per revocare una chiave, scorri fino alla sezione API Keys in Impostazioni, trova la chiave per nome e clicca su Revoca. La chiave smette di funzionare immediatamente. Le richieste in corso già autenticate verranno completate, ma nessuna nuova richiesta con la chiave revocata andrà a buon fine.