La documentación es el manual de un servicio
La documentación de una API es el manual de un servicio que construyó otra persona. Dice qué puedes pedir, qué debes enviar y qué vuelve.
Leerla rápido es una destreza básica. Convierte una descripción en una llamada que funciona.
Al final de esta lección
Nota
Puedo convertir la documentación de una API en una llamada que funciona.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| Endpoint | una ruta de URL que hace un solo trabajo | /v1/chat/completions |
| Parámetro | una entrada con nombre de una llamada | |
| Obligatorio | un parámetro que debes enviar | |
| Valor por defecto | el valor que se usa cuando no envías nada | |
| Tabla de errores | la lista de estados y de lo que significa cada uno |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Una página de documentación tiene cuatro partes
La mayoría de las páginas tienen las mismas cuatro cosas. El endpoint dice adónde enviar la llamada. La lista de parámetros dice qué puedes enviar. Un ejemplo muestra una llamada que funciona. La tabla de errores dice qué significa cada fallo.
Léelas en ese orden. La tabla siguiente es una página de ejemplo, escrita para esta lección.
Ejemplo resuelto: una lista de parámetros
| Parámetro | Tipo | Obligatorio | Por defecto |
|---|---|---|---|
| messages | lista | Sí | Ninguno |
| max_tokens | número entero, de 1 a 4096 | No | 256 |
| temperature | número, de 0 a 2 | No | 1 |
| stream | verdadero o falso | No | falso |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Haz la llamada que describe la página
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';(async()=>{const body={model:'lab',messages:[{role:'user',content:'Cita un uso de una API en cinco palabras.'}],max_tokens:30,temperature:0};console.log('Enviado: max_tokens='+body.max_tokens+', temperature='+body.temperature);try{const r=await fetch(u,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer lab'},body:JSON.stringify(body)});const j=await r.json();if(r.ok===false)throw new Error(r.status+' '+j.error.message);console.log('Modelo: '+j.choices[0].message.content)}catch(e){console.log('Sin respuesta ('+e.message+'). Muestra grabada:');console.log('Modelo: Obtener el tiempo para una aplicación.')}})()"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
El ejemplo muestra la forma
Copia primero el ejemplo y haz que funcione. Eso prueba que tu entorno va bien. Después cambia un parámetro cada vez y comprueba cada cambio en la lista de parámetros.
La lista te da el tipo, el rango y el valor por defecto. Un valor fuera del rango da un error, así que compruébalo antes de enviar.
Comprueba parámetros con la página
docker exec -w /home/node/project agent node -e "const spec={max_tokens:{min:1,max:4096},temperature:{min:0,max:2}};const check=(p)=>{const out=[];for(const k in p){if(spec[k]===undefined){out.push('desconocido '+k);continue}if(k==='max_tokens'&&Number.isInteger(p[k])===false)out.push(k+' debe ser un número entero');else if(p[k]<spec[k].min||p[k]>spec[k].max)out.push(k+' debe estar entre '+spec[k].min+' y '+spec[k].max)}return out};for(const p of [{max_tokens:50},{max_tokens:5000},{max_tokens:2.5,temperature:3},{top:1}])console.log(JSON.stringify(p)+' -> '+(check(p).join('; ')||'ok'))"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
La tabla de errores dice qué hacer
Una buena tabla de errores no se limita a nombrar un estado. Te dice si debes corregir tu llamada, esperar o intentarlo más tarde.
Un estado 4xx suele significar que cambies algo. Un estado 5xx significa que el servicio tiene un problema, así que reintentas más tarde.
Ejemplo resuelto: una tabla de errores
| Estado | Qué significa | Qué hacer |
|---|---|---|
| 400 | El cuerpo es incorrecto | Corregir el cuerpo |
| 401 | Falta la clave o es errónea | Revisar la clave |
| 403 | No permitido aquí | Leer el mensaje |
| 429 | Demasiadas peticiones | Esperar y reintentar |
| 503 | El servicio no está listo | Reintentar más tarde |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Lee un estado con la tabla de errores
docker exec -w /home/node/project agent node -e "const u=(process.env.AI_URL||'http://ai:4000')+'/v1/chat/completions';const advice={200:'funcionó, lee el cuerpo',400:'corrige el cuerpo',401:'revisa la clave',403:'lee el mensaje',429:'espera y reintenta',503:'reintenta más tarde'};(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:'Di hola.'}],max_tokens:10})});console.log('Estado '+r.status+': '+(advice[r.status]||'no está en la tabla'));if(r.status>299)console.log('Muestra grabada de una llamada buena: Estado 200: '+advice[200])}catch(e){console.log('Sin respuesta del servicio ('+e.message+'). Muestra grabada:');console.log('Estado 429: '+advice[429])}})()"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Un error frecuente
Advertencia
Mucha gente cree que el ejemplo de la documentación es toda la API. Un ejemplo muestra una sola llamada. La lista de parámetros dice qué más puedes enviar, y la tabla de errores dice qué hacer cuando una llamada falla. Lee las tres.