Modèle : documentation d’API

Type d'information :Référence•"Quels sont les détails ?"

Données de référence, syntaxe exacte, paramètres et contraintes

Modèle

Ceci est un point de départ à copier et adapter, pas un exemple abouti. C’est une instance spécialisée du modèle d’article référence, adaptée à un endpoint d’API par page. Pour approfondir la relation entre documentation de référence, schémas OpenAPI et guides pas-à-pas, consultez Typologie de l’information et documentation d’API.

Utilisez une copie de ce modèle par endpoint (ou par groupe d’endpoints étroitement liés, comme GET/POST sur la même ressource). N’essayez pas de documenter une API entière sur une seule page - elle cesse d’être consultable au-delà de quelques endpoints.

---
title: "<Méthode HTTP> <chemin>"
description: "<Une phrase : ce que fait cet endpoint>"
contentType: reference
---

## Aperçu

<Une ou deux phrases : à quoi sert cet endpoint et quand l'appeler.>

## Endpoint

```
<MÉTHODE> <chemin>
```

## Authentification

<Schéma d'authentification requis, ou « Aucune » si l'endpoint est public.>

## Paramètres

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `<nom>` | chemin / requête / corps | `<type>` | Oui/Non | <ce qu'il fait> |

## Exemple de requête

```bash
curl -X <MÉTHODE> https://api.exemple.com/<chemin> \
  -H "Content-Type: application/json" \
  -d '{ "<champ>": "<valeur>" }'
```

## Exemple de réponse

```json
{
  "<champ>": "<valeur>"
}
```

## Codes d'erreur

| Statut HTTP | Code | Signification |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | <quand cela se produit> |
| 404 | `NOT_FOUND` | <quand cela se produit> |

## Endpoints connexes

- [<Endpoint connexe>](<lien>)

Notes de remplissage

• Chaque champ des tableaux doit provenir du contrat réel de l’API - le schéma, le code de validation, ou une requête/réponse réellement capturée. N’inventez jamais un paramètre ou un code d’erreur plausible ; c’est pire qu’une absence de documentation, car le lecteur s’y fiera.
• Gardez les exemples de requête/réponse exécutables tels quels - un lecteur doit pouvoir copier-coller la commande curl et obtenir la réponse indiquée (en masquant uniquement les vrais secrets).
• Si l’API dispose d’un contrat lisible par machine (comme une spécification OpenAPIOpenAPIFormat normalisé et lisible par machine (YAML ou JSON) qui décrit une API HTTP : endpoints, paramètres, schémas de requête et de réponse, codes d'état. La documentation de référence peut en être générée ; le rédacteur y ajoute les conseils d'usage que la description ne peut pas porter.Voir dans le glossaire → ou un schéma JSON), générez la documentation à partir de celui-ci ou liez-le directement plutôt que de dupliquer manuellement chaque champ qu’il définit déjà - les tables manuelles et les contrats machine finiraient par diverger. Rédigez des pages de référence MarkdownMarkdownLangage de balisage léger en texte brut, où la mise en forme s'exprime par une ponctuation simple, par exemple un # en début de ligne pour un titre. Facile à rédiger et à relire sous gestion de versions, il n'impose aucun schéma : les équipes docs-as-code compensent par des modèles et des contrôles automatisés. Ce manuel est rédigé en MDX, une variante de Markdown.Voir dans le glossaire → manuelles lorsque vous devez apporter des explications nuancées, des cas limites ou du contexte métier spécifique.
• Pour un exemple opérationnel de documentation publiée avec son contrat lisible par machine, voir l’API de ce manuel : son /schema.json décrit chaque endpoint, et la page de référence ajoute les conseils d’usage que le schéma ne peut pas porter.