Le contrat OpenAPI

Le contrat OpenAPI est un fichier JSON qui décrit chaque route de l'API : son adresse, ses paramètres, ses réponses, son périmètre et ses erreurs. Un outil le lit sans aide : un générateur de client, un éditeur d'API ou une IA.

Où le lire

Les deux se lisent avec un simple GET, sans clé, et ne coûtent aucun crédit. L'API laisse garder son document cinq minutes (Cache-Control) et envoie un ETag : relis-le avec If-None-Match et tu reçois un 304 quand rien n'a changé. Pour lire ce que l'API sert à l'instant, prends l'adresse de l'API.

Sa version

La version du contrat est dans info.version. Lis-la avec une commande qui n'a pas besoin de clé :

curl -s https://api.fitdistance.io/api/partner/v1/openapi.json | jq -r '.info.version'

Elle vaut 1.0.0 aujourd'hui. Le document suit OpenAPI 3.1. Il déclare un seul serveur, https://api.fitdistance.io/api/partner/v1, et un seul schéma de sécurité : ta clé dans l'en-tête Authorization: Bearer.

Ce que tu y trouves

• Les routes de lecture, comme GET /students, avec leurs paramètres, leurs champs de réponse et leurs erreurs.
• Les opérations, une adresse chacune : POST /operations/<nom>. Le contrat décrit leurs arguments et l'enveloppe de leur réponse, pas le contenu de data, qui dépend de l'opération.
• Sur chaque opération, des champs x- : x-scope (le périmètre), x-kind (lecture, écriture ou suppression), x-kind-by-action (la nature de chaque valeur de action, pour une opération qui en porte plusieurs), x-sensitive (les périmètres sensibles à ajouter), x-confirmable (un aperçu avec dry_run est possible) et x-stability.

x-stability vaut experimental sur les opérations : leur data est la réponse interne telle quelle et peut encore changer. Les routes de lecture sont la surface stable : leurs schémas sont figés.

Générer un client

Un générateur lit le contrat et écrit le code d'un client. Voici deux exemples, une commande chacun.

Des types TypeScript, avec openapi-typescript :

npx openapi-typescript https://fitdistance.io/documentation/api/openapi.json -o fitdistance-api.d.ts

Un client TypeScript, avec openapi-generator-cli (il demande Java) :

npx @openapitools/openapi-generator-cli generate -i https://fitdistance.io/documentation/api/openapi.json -g typescript-fetch -o ./fitdistance-client-fetch

Ce sont des exemples : Fit'Distance ne livre pas de client généré, et la source reste le contrat. Un générateur peut échouer sur une partie du contrat : essaie alors un autre langage. Mets ta clé dans l'en-tête de ton client, jamais dans un code que tu partages. Le champ data d'une opération n'étant pas décrit, ne compte pas sur un type généré pour lui.

Ce que la référence en tire

La référence lit dans ce document les routes, leurs paramètres, leurs périmètres, leurs schémas et leurs codes d'erreur. Le site y ajoute les mentions de coût (« Gratuit », « 1 crédit » et la colonne « facturé » des tableaux d'erreurs) et l'étiquette « Stable » des routes de lecture : elles ne sont pas dans le contrat. Les routes sans famille, dont GET /openapi.json, sont dans Général.

La suite

GET /operations complète le contrat : c'est lui qui fait foi sur la nature (kind) et le périmètre (scope) de chaque opération, et il se lit sans clé. Pour une IA, llms.txt et llms-full.txt donnent le même contenu en texte, et le serveur MCP lui ouvre tes données.