La documentation est le mode d’emploi d’un service
La documentation d’une API est le mode d’emploi d’un service construit par quelqu’un d’autre. Elle liste ce que vous pouvez demander, ce qu’il faut envoyer et ce qui revient.
La lire vite est une compétence centrale. Elle transforme une description en appel qui marche.
À la fin de cette leçon
Remarque
Je peux transformer la documentation d’une API en un appel qui marche.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| Point d’accès | un chemin d’URL qui fait un seul travail | /v1/chat/completions |
| Paramètre | une entrée nommée d’un appel | |
| Obligatoire | un paramètre que vous devez envoyer | |
| Valeur par défaut | la valeur utilisée quand vous n’envoyez rien | |
| Tableau des erreurs | la liste des statuts et de leur sens |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une page de documentation a quatre parties
La plupart des pages contiennent les mêmes quatre choses. Le point d’accès dit où envoyer l’appel. La liste des paramètres dit ce que vous pouvez envoyer. Un exemple montre un appel qui marche. Le tableau des erreurs dit ce que chaque échec veut dire.
Lisez-les dans cet ordre. Le tableau suivant est une page d’exemple, écrite pour cette leçon.
Exemple travaillé : une liste de paramètres
| Paramètre | Type | Obligatoire | Par défaut |
|---|---|---|---|
| messages | liste | Oui | Aucune |
| max_tokens | nombre entier, de 1 à 4096 | Non | 256 |
| temperature | nombre, de 0 à 2 | Non | 1 |
| stream | vrai ou faux | Non | faux |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Faire l’appel que décrit la page
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';(async()=>{const corps={model:'lab',messages:[{role:'user',content:'Citez un usage d’une API en cinq mots.'}],max_tokens:30,temperature:0};console.log('Envoyé : max_tokens='+corps.max_tokens+', temperature='+corps.temperature);try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify(corps)});const j=await r.json();if(r.ok===false)throw new Error(r.status+' '+j.error.message);console.log('Modèle : '+j.choices[0].message.content)}catch(e){console.log('Aucune réponse du modèle ('+e.message+'). Exemple enregistré :');console.log('Modèle : Récupérer la météo pour une application.')}})()"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
L’exemple montre la forme
Copiez d’abord l’exemple et faites-le marcher. Cela prouve que votre installation fonctionne. Changez ensuite un paramètre à la fois, et vérifiez chaque changement dans la liste des paramètres.
La liste donne le type, l’intervalle et la valeur par défaut. Une valeur hors de l’intervalle donne une erreur : contrôlez-la avant d’envoyer.
Contrôler des paramètres d’après la page
docker exec -w /home/node/project agent node -e "const spec={max_tokens:{bas:1,haut:4096},temperature:{bas:0,haut:2}};const controle=(p)=>{const sortie=[];for(const k in p){if(spec[k]===undefined){sortie.push('inconnu '+k);continue}if(k==='max_tokens'&&Number.isInteger(p[k])===false)sortie.push(k+' doit être un nombre entier');else if(p[k]<spec[k].bas||p[k]>spec[k].haut)sortie.push(k+' doit aller de '+spec[k].bas+' à '+spec[k].haut)}return sortie};for(const p of [{max_tokens:50},{max_tokens:5000},{max_tokens:2.5,temperature:3},{top:1}])console.log(JSON.stringify(p)+' -> '+(controle(p).join(' ; ')||'ok'))"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Le tableau des erreurs dit quoi faire
Un bon tableau des erreurs ne se contente pas de nommer un statut. Il dit s’il faut corriger votre appel, attendre ou réessayer plus tard.
Un statut 4xx veut en général dire que vous changez quelque chose. Un statut 5xx veut dire que le service a un problème : vous réessayez plus tard.
Exemple travaillé : un tableau des erreurs
| Statut | Sens | Que faire |
|---|---|---|
| 400 | Le corps est incorrect | Corriger le corps |
| 401 | Clé absente ou fausse | Vérifier la clé |
| 403 | Accès refusé ici | Lire le message |
| 429 | Trop de requêtes | Attendre, puis réessayer |
| 503 | Service pas prêt | Réessayer plus tard |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Lire un statut avec le tableau des erreurs
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const conseil={200:'ça a marché, lisez le corps',400:'corrigez le corps',401:'vérifiez la clé',403:'lisez le message',429:'attendez, puis réessayez',503:'réessayez plus tard'};(async()=>{try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify({model:'lab',messages:[{role:'user',content:'Dites salut.'}],max_tokens:10})});console.log('Statut '+r.status+' : '+(conseil[r.status]||'absent du tableau'));if(r.status>299)console.log('Exemple enregistré d’un bon appel : Statut 200 : '+conseil[200])}catch(e){console.log('Aucune réponse du service ('+e.message+'). Exemple enregistré :');console.log('Statut 429 : '+conseil[429])}})()"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Une erreur fréquente
Attention
Beaucoup de gens pensent que l’exemple de la documentation est toute l’API. Un exemple montre un seul appel. La liste des paramètres dit ce que vous pouvez envoyer d’autre, et le tableau des erreurs dit quoi faire quand un appel échoue. Lisez les trois.