# À 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 :

```mermaid
%%{init: {"flowchart": {"curve": "basis"}, "themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif"}}}%%
flowchart TD
    accTitle: Pipeline de récupération de l'API
    accDescr: Pipeline de récupération séquentiel en quatre étapes : découverte du contrat, interrogation de l'index, sélection du document et récupération du Markdown.

    A["GET /schema.json"] --> B["Découverte des endpoints, filtres et taxonomie"]
    B --> C["Interroger l'index des documents"]
    C --> D["Sélectionner le document cible"]
    D --> E["Suivre l'URL markdown annoncée"]
    E --> F["Récupérer le document Markdown"]

    classDef stage fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px,color:#0f172a,font-weight:500
    classDef endpoint fill:#e2e8f0,stroke:#3b82f6,stroke-width:1.5px,color:#1e293b,font-weight:600

    class A,C,F endpoint
    class B,D,E stage

    linkStyle default stroke:#64748b,stroke-width:1.5px
```

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 :
   ```bash
   GET /schema.json
   ```
2. **Filtrer** : interroger l'index avec les filtres et projections de champs souhaités :
   ```bash
   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 :
   ```bash
   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.

## 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](https://llmstxt.org/) — 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 :

```json
{
  "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

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

### 2. Lister les documents de tâches

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

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

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

### 4. Récupérer un document Markdown propre

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

### 5. Paginer les résultats d'index

```bash
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` :

```javascript
// 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](https://docs.redaction-technique.org/fr/) 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](https://docs.redaction-technique.org/fr/reference/)
- [Glossaire](https://docs.redaction-technique.org/fr/reference/glossary/)

---

Source: https://docs.redaction-technique.org/fr/about-the-api/