API de contenu public

L'API de contenu public vous donne un accès programmatique en lecture seule aux articles de blog de votre organisation Nolorem. Utilisez-la pour récupérer du contenu vers un site Drupal, un front-end personnalisé, une application mobile ou tout système externe qui a besoin de vos données de blog.

L'API est disponible avec l'offre Premium. Tout accès se fait en lecture seule ; la publication et l'édition restent dans Nolorem.

Créer une clé API

Seuls les administrateurs de l'organisation peuvent créer des clés API.

1. Dans Paramètres, faites défiler jusqu'à la section Clés API (visible uniquement par les administrateurs).
2. Cliquez sur Créer une clé API.
3. Saisissez un nom descriptif pour la clé (par exemple, « Site web Drupal » ou « Script de synchronisation du contenu »).
4. Choisissez la portée de la clé (voir ci-dessous).
5. Copiez la clé affichée à l'écran. Elle commence par nlr_live_.

La clé n'est affichée qu'une seule fois. Stockez-la immédiatement dans un gestionnaire de secrets ou une variable d'environnement. Si vous la perdez, révoquez la clé et créez-en une nouvelle.

Choisir la portée d'une clé

Lorsque vous créez une clé, vous choisissez si elle couvre un blog spécifique ou tous les blogs de votre organisation.

Clé limitée à un blog (recommandé) : la clé est liée à un seul blog. Elle ne peut accéder qu'aux articles, catégories et tags de ce blog. Si la clé venait à être divulguée ou partagée, seul le contenu de ce blog serait exposé.

Clé à l'échelle de l'organisation : la clé a accès à tous les blogs de votre organisation. N'utilisez cette portée que lorsque vous avez une raison délibérée d'accéder à plusieurs blogs avec une seule clé.

Le badge de portée sur chaque clé de la liste indique à quel blog la clé est liée, ou « Tous les blogs » pour une clé à l'échelle de l'organisation. La portée est fixée à la création. Pour la modifier, créez une nouvelle clé avec la portée souhaitée, mettez à jour tous les consommateurs, puis révoquez l'ancienne clé.

Authentifier les requêtes

Passez la clé dans l'en-tête Authorization de chaque requête :

Authorization: Bearer nlr_live_your_key_here

Exemple avec curl :

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

L'API est de serveur à serveur. Il n'y a pas d'en-têtes CORS, donc les clients navigateurs ne peuvent pas l'appeler directement. Effectuez tous les appels API depuis votre back-end ou un script côté serveur.

Lister vos blogs

GET /api/v1/blogs liste les blogs auxquels votre clé peut accéder. La forme de la réponse est la même que la clé soit limitée à un blog ou à l'échelle de l'organisation.

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

Réponse :

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

Une clé limitée à un blog renvoie exactement une entrée (le blog lié). Une clé à l'échelle de l'organisation renvoie tous les blogs. Utilisez ce point de terminaison pour découvrir quels blogs une clé couvre avant de récupérer du contenu.

Filtrer les articles par blog

Tous les points de terminaison de contenu acceptent un paramètre blog facultatif. Passez soit l'UUID du blog, soit son slug :

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

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

Si vous omettez blog, l'API renvoie le contenu de tous les blogs auxquels votre clé peut accéder (le comportement par défaut, non contraignant).

Si vous utilisez une clé limitée à un blog et passez ?blog= pointant vers un autre blog, l'API renvoie 403 Forbidden. Cela empêche de deviner quels blogs existent dans une organisation.

Le même paramètre blog fonctionne sur /api/v1/categories et /api/v1/tags.

Lister les articles

GET /api/v1/posts renvoie une liste paginée d'articles pour les blogs accessibles à votre clé. Par défaut, il renvoie les articles publiés, 20 par page.

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

Réponse :

{
  "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 }
}

Le champ html est toujours null dans les réponses de liste. Utilisez les points de terminaison de détail pour obtenir le corps complet de l'article.

Filtres disponibles

Paramètre	Description	Exemple
blog	UUID ou slug du blog (par défaut : tous les blogs accessibles)	blog=my-blog
status	published, draft ou scheduled (par défaut : published)	status=published
language	Code de langue ISO 639-1	language=nl
category	Nom de catégorie (insensible à la casse)	category=Technology
tag	Nom de tag (insensible à la casse)	tag=AI
updated_since	Date-heure ISO 8601 ; uniquement les articles modifiés après cette date	updated_since=2026-06-01T00:00:00Z
page	Numéro de page, à partir de 1	page=2
per_page	Éléments par page, 100 maximum	per_page=100

Récupérer un seul article

Récupérez un article par son UUID pour obtenir le corps HTML complet :

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

Ou par son slug :

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

Les deux renvoient un seul objet PublicPost (non enveloppé dans un tableau data) avec le champ html renseigné.

Synchronisation incrémentielle avec updated_since

Pour synchroniser uniquement le contenu nouveau ou modifié, stockez l'horodatage de votre dernière synchronisation réussie et passez-le comme updated_since lors de la prochaine exécution :

# Synchronisation initiale : récupérer tous les articles publiés
curl "https://nolorem.io/api/v1/posts?per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Synchronisations suivantes : uniquement les articles modifiés depuis la dernière synchronisation
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"

Parcourez tous les résultats page par page avant de stocker votre nouvel horodatage de synchronisation.

Détecter les articles dépubliés ou supprimés

Lorsque vous utilisez updated_since pour la synchronisation incrémentielle, la réponse par défaut ne renvoie que les articles qui sont toujours publiés. Si un article a été dépublié ou supprimé dans Nolorem depuis votre dernière synchronisation, il disparaît simplement des résultats sans aucun signal pour le retirer sur la destination.

Pour obtenir ce signal, passez include_deleted=true en même temps que votre horodatage 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 réponse inclut tous les articles actifs comme d'habitude, plus des entrées « tombstone » (marqueurs de suppression) minimales ajoutées à la fin de data. Chaque tombstone contient :

• id : l'UUID de l'article que vous avez déjà d'une synchronisation précédente
• status : le statut actuel de l'article, ou "deleted" s'il a été supprimé définitivement
• updated_at : le moment où le changement s'est produit
• deleted : true si l'article a été supprimé, false s'il a simplement été dépublié ou remis en brouillon

{
  "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 }
}

Utilisez meta.tombstones pour connaître le nombre d'entrées tombstone ajoutées. meta.total reflète toujours uniquement les articles actifs.

Lorsque votre outil de synchronisation voit un tombstone, dépubliez ou retirez la page correspondante sur la destination (par exemple, mettez le nœud Drupal correspondant en dépublié ou en brouillon).

Sans include_deleted=true, le comportement est identique à celui d'avant ce changement : seuls les articles actifs et publiés sont renvoyés.

Lister les catégories et les tags

Deux points de terminaison renvoient la taxonomie complète des catégories et des tags de votre blog. Ils sont utiles aux outils externes qui ont besoin de faire correspondre les catégories ou les tags Nolorem à leur propre taxonomie (par exemple, un connecteur Drupal faisant correspondre les catégories Nolorem aux termes de vocabulaire Drupal). Les deux acceptent le paramètre blog.

# Toutes les catégories de votre organisation (ou du blog limité)
curl "https://nolorem.io/api/v1/categories?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Tous les tags de votre organisation (ou du blog limité)
curl "https://nolorem.io/api/v1/tags?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Les deux renvoient la liste complète dans une seule réponse (non paginée) :

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

Le même jeton bearer, la même exigence de l'offre Premium et la même portée posts:read s'appliquent que pour les points de terminaison des articles.

Analyses d'utilisation par clé

Dans les Paramètres, chaque ligne de clé peut être développée pour afficher des analyses d'utilisation :

• Requêtes (dernières 24 h / total) : combien d'appels API cette clé a effectués.
• Sources distinctes : combien d'adresses IP et d'applications clientes distinctes ont utilisé cette clé récemment.
• Dernière utilisation : l'horodatage de la requête authentifiée la plus récente.

Ces analyses vous aident à comprendre comment vos clés sont utilisées et à repérer des schémas inattendus.

Indicateur de partage de clé

Si une clé affiche un grand nombre d'adresses IP distinctes sur une courte période, Nolorem peut la signaler comme « peut-être partagée ou compromise ». L'indicateur apparaît sous la forme d'un avertissement ambre sur la ligne de la clé. La clé continue de fonctionner et aucune action automatique n'est prise : il s'agit d'un signal indicatif.

Lorsque vous voyez l'indicateur, examinez vos journaux d'utilisation. Si vous avez partagé la clé intentionnellement (par exemple, avec plusieurs serveurs d'un cluster), demandez-vous si le schéma d'accès est attendu. Si la clé a pu être divulguée ou partagée avec des parties non prévues, révoquez-la et créez-en une nouvelle pour limiter l'accès.

Limites de débit

Chaque clé API est soumise à ces limites :

• 60 requêtes par minute
• 5 000 requêtes par jour

Lorsque vous dépassez une limite, l'API renvoie un HTTP 429 avec un en-tête Retry-After indiquant combien de secondes attendre avant de réessayer :

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

{ "error": "Rate limit exceeded" }

Mettez en place un backoff exponentiel pour des scripts de synchronisation de longue durée fiables.

Codes d'erreur

Statut	Signification
400	Paramètres de requête invalides
401	Clé API manquante ou invalide
403	Offre Premium requise, la clé n'a pas la portée posts:read, ou clé limitée à un blog utilisée avec une valeur ?blog= non concordante
404	Article introuvable
429	Limite de débit dépassée (vérifiez l'en-tête Retry-After)

Spécification lisible par machine

La spécification complète de l'API au format OpenAPI 3.1 est disponible à :

GET /api/v1/openapi.json

Ce point de terminaison ne nécessite pas d'authentification. Vous pouvez l'importer dans Postman, Insomnia ou tout outil compatible OpenAPI.

Révoquer une clé

Pour révoquer une clé, faites défiler jusqu'à la section Clés API dans les Paramètres, trouvez la clé par son nom et cliquez sur Révoquer. La clé cesse de fonctionner immédiatement. Les requêtes en cours qui étaient déjà authentifiées se termineront, mais aucune nouvelle requête avec la clé révoquée n'aboutira.