À propos de l'API de ce manuel

Aperçu

Ce manuel n’est pas seulement une démo OpenAPI hébergée ailleurs dans la famille redaction-technique.org - l’API propre à ce site est bien réelle, et elle fonctionne déjà sous chaque page que vous lisez. C’est un ensemble d’endpoints statiques, sans exécution serveur, qui reproduit l’intégralité du corpus documentaire sous une forme consultable par machine, destinée aux LLM, aux agents de codage IA et à l’outillage automatisé, pour être consommée directement plutôt que par extraction du HTML rendu.

Tout ce qui suit est généré au moment du build à partir des mêmes sources Markdown que les pages HTML - il n’y a pas de contenu séparé à synchroniser, ni de base de données ou de fonction serveur impliquée. C’est servi comme des fichiers statiques depuis le CDN en périphérie, comme n’importe quel autre asset de ce site.

Pourquoi elle existe

Le HTML rendu est conçu pour les navigateurs : habillage de navigation, CSS, interactivité côté client. Un LLM ou un agent qui n’a besoin que du texte de l’article doit retirer tout cela, et peut s’y mal prendre. Cette API évite l’aller-retour : elle sert directement le même contenu que les agents reconstruiraient autrement, sous forme de Markdown propre et de JSON structuré.

Flux de travail rapide (Quick start)

L’API s’articule autour d’un pipeline de récupération séquentiel en quatre étapes :

Les quatre étapes de récupération avec leurs requêtes HTTP correspondantes :

1. Découvrir : récupérer le contrat de découverte pour explorer les endpoints, la taxonomie et les paramètres de requête disponibles :

   GET /schema.json

2. Filtrer : interroger l’index avec les filtres et projections de champs souhaités :

   GET /fr/index.json?contentType=task&fields=title,url,markdown,contentType

3. Sélectionner : identifier le document cible parmi les résultats (ex. « tutorials/auto-insert-data-dita-xml/ ») et lire sa propriété markdown annoncée.
4. Récupérer : suivre l’URL annoncée pour télécharger le Markdown source propre :

   GET /fr/tutorials/auto-insert-data-dita-xml.md

Découvrir → Filtrer → Sélectionner → Récupérer

les consommateurs découvrent les capacités depuis /schema.json, interrogent l’index pour filtrer les rubriques pertinentes, identifient l’URL Markdown associée et téléchargent directement le texte source propre.

Explorateur de documentation

Utilisez l’explorateur de documentation pour parcourir le corpus de manière interactive. Chaque résultat expose également la représentation Markdown canonique pour une consommation programmatique ou par des LLM.

Explorer la documentationRechercher et filtrer la documentationPoser une questionObtenir une réponse fondée sur la documentation

Rechercher dans les rubriques documentaires

LangueEnglishFrançaisToutes les langues

Type d'informationTous les types d'informationConceptTâcheRéférence

Rôle structurelTous les rôlesSujet (Topic)IndexPage de renvoi (Landing)Vue d'ensemble (Overview)Utilitaire (Utility)

Chargement de l’index documentaire…

Copier la requête d'API

Endpoints

Endpoint	Format	À quoi il sert
/schema.json	JSON	Contrat de découverte d’API consultable par machine définissant les endpoints, les paramètres de requête, le schéma de document et la taxonomie auto-descriptive.
/llms.txt	Texte brut	Une table des matières concise conforme à la convention llms.txt - le point d’entrée pour un agent qui veut savoir ce qui existe ici avant de récupérer quelque chose de plus volumineux.
/llms-full.txt, /llms-full-en.txt, /llms-full-fr.txt	Texte brut	Le corpus entier (bilingual, ou une seule langue) concaténé en un seul fichier, pour un agent qui veut tout ingérer en une seule requête plutôt qu’une par page.
/index.json, /en/index.json, /fr/index.json	JSON	Un index de documents consultable par machine : titre, description, URL, nombre de mots, titres, tags, pageType, contentType et définitions de taxonomie pour chaque page, avec prise en charge du filtrage par paramètres d’URL.
/sitemap.md, /en/sitemap.md, /fr/sitemap.md	Markdown	Un plan de site hiérarchique regroupé par section, dans un format qu’un LLM peut lire directement plutôt que d’analyser un sitemap XML.
/en/<page>.md, /fr/<page>.md	Markdown	Un miroir Markdown propre d’une page - le même contenu textuel que la version HTML, sans la mise en page ni le balisage de navigation.

Le contenu de l’endpoint .md de chaque page est garanti identique octet pour octet à la section correspondante dans llms-full.txt - un test automatisé de ce dépôt vérifie cet invariant à chaque build, sur l’ensemble des documents, pas seulement par sondage.

Découverte automatique via /schema.json

Les clients d’API, outils de recherche et pipelines LLM/RAG n’ont pas besoin de coder en dur des listes d’URL ou de classifications. L’endpoint /schema.json fait office de contrat de découverte d’API consultable par machine.

À partir de /schema.json, un consommateur externe peut découvrir :

• Endpoints disponibles : URL des index globaux, anglais et français, et localisation des ressources (schema.endpoints).
• Langues prises en charge : en et fr (schema.filters.lang).
• Types d’information : valeurs canoniques de contentType (concept, task, reference) et définitions explicites (schema.taxonomy.contentType).
• Types structurels de page : valeurs canoniques de pageType (topic, index, landing, overview, utility) et descriptions (schema.taxonomy.pageType).
• Paramètres de requête : clés acceptées (contentType, pageType, lang, fields, page, limit), types, valeurs par défaut et limites autorisées (schema.queryParameters).
• Propriétés de document : structure canonique d’une notice (title, url, markdown, locale, pageType, contentType, wordCount, headings, keywords, tags) et champs obligatoires (schema.document).
• Modèle d’accès et d’identité : identifiant canonique (url) et formats de représentation (schema.retrieval).
• Règles de pagination : page minimale (1), limites (1 à 100, valeur par défaut 20) et gestion stricte des dépassements (schema.queryParameters).

Métadonnées des documents et typage de l’information

Chaque notice documentaire de l’index JSON expose deux dimensions de classification complémentaires :

• pageType : décrit le rôle structurel d’une page au sein du site documentaire (topic, index, landing, overview, utility).
• contentType : décrit le type d’information principal et l’intention du lecteur (concept, task, reference), ou null pour les pages délibérément non typées.

Distinction sémantique

pageType décrit le rôle structurel d’une page dans le site documentaire. contentType décrit le type d’information principal et l’intention du lecteur.

Par exemple, une notice comportant :

{
  "pageType": "topic",
  "contentType": "task"
}

représente un sujet documentaire opérationnel et orienté tâche (comme un didacticiel ou un guide de procédure étape par étape).

Pages délibérément non typées

Les pages d’organisation et de navigation - telles que les vues d’ensemble de section, les index de répertoires, les pages de renvoi (landing pages) et les utilitaires de recherche - possèdent un pageType structurel explicite (par exemple landing, overview, utility), mais ont contentType: null. Elles ne sont pas artificiellement rattachées aux archétypes Concept, Tâche ou Référence.

Filtrage par paramètres d’URL

L’index de documentation JSON prend en charge le filtrage par paramètres de requête via une opération logique ET (AND) :

Filtre	Exemple	Description
Type d’information	?contentType=concept	Renvoie uniquement les explications conceptuelles
	?contentType=task	Renvoie uniquement les articles de tâches pas à pas
	?contentType=reference	Renvoie uniquement les rubriques de référence
Type structurel de page	?pageType=topic	Renvoie uniquement les sujets documentaires standard
	?pageType=overview	Renvoie les pages de vue d’ensemble de section
Filtre combiné	?pageType=topic&contentType=task	Renvoie les sujets documentaires orientés tâche satisfaisant les deux conditions
Filtre de langue	?lang=fr&contentType=concept	Renvoie les pages de concepts en français avec stricte isolation linguistique

Les valeurs de paramètres non valides (comme ?contentType=tutorial ou une casse non conforme comme ?contentType=Concept) renvoient une réponse HTTP 400 accompagnée d’un objet d’erreur détaillant les valeurs canoniques autorisées.

Utilisation par les LLM et agents IA

Les agents automatisés, assistants de code et systèmes RAG peuvent consommer le site de manière systématique sans parsing heuristique de HTML :

1. Découvrir les capacités : interroger /schema.json pour connaître les endpoints, dimensions taxonomiques et paramètres acceptés.
2. Inspecter la taxonomie et les filtres : identifier les clés adéquates (par exemple contentType=task pour les procédures, contentType=concept pour les explications de fond).
3. Interroger l’index avec projection de champs : exécuter une requête avec fields=title,url,markdown,contentType pour minimiser la taille du payload et économiser les jetons de contexte.
4. Sélectionner les documents cibles : identifier les documents pertinents par titre ou URL d’après la question posée.
5. Récupérer le Markdown propre : suivre l’URL renseignée dans la propriété markdown pour obtenir le document source.
6. Alimenter le contexte du modèle : intégrer le Markdown épuré directement comme source de vérité.

Pourquoi le Markdown pour les consommateurs LLM ?

• Représentation textuelle pure : aucune barre de navigation, pied de page ni script client ne vient polluer la fenêtre de contexte.
• Efficience des jetons : supprime le balisage HTML inutile et réserve le budget de contexte au contenu substantiel.
• Directement exploitable : titres, listes, extraits de code et tableaux restent dans une syntaxe Markdown claire et standardisée.
• URL d’accès stable : chaque document annonce directement l’URL de son miroir Markdown dans ses métadonnées d’index.

Exemples curl prêts à l’emploi

1. Découvrir l’API et ses capacités

curl https://docs.redaction-technique.org/schema.json

2. Lister les documents de tâches

curl 'https://docs.redaction-technique.org/fr/index.json?contentType=task'

3. Réduire les champs renvoyés (projection économe en jetons)

curl 'https://docs.redaction-technique.org/fr/index.json?contentType=task&fields=title,url,markdown,contentType'

4. Récupérer un document Markdown propre

curl https://docs.redaction-technique.org/fr/tutorials/auto-insert-data-dita-xml.md

5. Paginer les résultats d’index

curl 'https://docs.redaction-technique.org/fr/index.json?contentType=task&page=1&limit=10'

Exemple consommateur en JavaScript

Voici un exemple minimal et complet montrant comment un outil externe peut découvrir, filtrer et récupérer du contenu en utilisant uniquement l’API standard fetch :

// 1. Récupération du contrat de découverte
const schema = await fetch('https://docs.redaction-technique.org/schema.json')
  .then((res) => res.json());

// 2. Découverte de l'endpoint de l'index français
const frIndexUrl = schema.endpoints.fr.index;

// 3. Récupération des sujets de tâches avec projection de champs
const params = new URLSearchParams({
  contentType: 'task',
  fields: 'title,url,markdown,contentType',
});
const index = await fetch(`${frIndexUrl}?${params}`)
  .then((res) => res.json());

// 4. Sélection d'un document de tâche spécifique
const taskDoc = index.documents.find((doc) =>
  doc.url.includes('auto-insert-data-dita-xml')
);

// 5. Récupération de la version Markdown propre
const markdown = await fetch(taskDoc.markdown)
  .then((res) => res.text());

console.log(`Récupéré : "${taskDoc.title}" (${markdown.length} octets) :`);
console.log(markdown.slice(0, 160));

Principes de stabilité de l’API et garanties contractuelles

Cette API est traitée comme une infrastructure documentaire pérenne :

• L’identifiant stable est l’url canonique : l’URL canonique (ex. https://docs.redaction-technique.org/fr/tutorials/auto-insert-data-dita-xml/) constitue l’identifiant unique, déterministe et garanti stable entre les builds pour chaque document.
• Représentation Markdown directe : la propriété markdown renvoie toujours vers le miroir Markdown propre, strictement identique octet pour octet à sa section dans llms-full.txt.
• Rétrocompatibilité : les réponses d’index sans paramètres (/index.json, /en/index.json, /fr/index.json) conservent leur schéma et leur compatibilité ascendante.
• Taxonomie canonique : les valeurs de taxonomie (contentType et pageType) sont validées contre des référentiels stricts. Tout ajout est réalisé de façon concertée et symétrique.
• Schéma synchronisé et tests de contrat : toute évolution des endpoints, de la taxonomie ou des filtres met à jour simultanément /schema.json et la suite de tests de contrat en boîte noire (tests/api-contract.test.mjs).

Comment chaque page l’expose

Vous n’avez pas besoin de connaître ces URL par cœur - chaque page renvoie vers sa propre forme consultable par machine :

• Des balises <link rel="alternate"> dans le <head> de la page pointent vers le fichier .md de la page, l’index de la langue concernée et /llms.txt - détectables par tout outil qui lit les métadonnées d’en-tête HTML, sans JavaScript.
• Le bouton « Copy for LLM » (visible en haut de chaque page) copie le Markdown propre de cette page directement dans le presse-papiers - utile pour coller une page directement dans une conversation avec un assistant IA.
• Le lien « View as Markdown » est une simple balise <a> vers le fichier .md - fonctionne avec JavaScript désactivé, et correspond exactement à ce qu’un agent suivant la balise de découverte récupérerait.

Par rapport à « Interroger la documentation »

Cette API et l’assistant IA de la page d’accueil résolvent des problèmes différents. L’API sert à ce que vos propres outils et agents importent le contenu de ce manuel dans leur contexte - un agent de codage qui veut l’article docs-as-code directement dans son flux de travail, par exemple. L’assistant de la page d’accueil, c’est l’inverse : c’est ce site qui répond à une question pour vous, fondée sur son propre contenu, sans clé d’API ni intégration nécessaire de votre côté.

Références connexes

• Explorer la référence
• Glossaire