Interpretación de Peticiones y Respuestas API con HTTP y JSON

¡Hola! En la lección anterior seguiste los datos de un asistente de devoluciones desde la consulta de una persona hasta el sistema de pedidos, el modelo y los registros. Ahora vamos a acercarnos a una de esas conexiones: una petición a una API y la respuesta que recibe.

El objetivo no es programar todavía. Es poder mirar un intercambio sencillo y explicar qué operación se solicitó, qué datos viajaron, qué contestó el servicio y qué no se puede concluir solo con esa respuesta. Esa lectura te ayudará a conversar con equipos técnicos y, en la próxima lección, a entender el script que enviará una petición a una API de IA.

Una conversación con estructura: HTTP

Una API permite que una aplicación solicite a otra una operación o unos datos mediante una interfaz definida. En nuestro ejemplo, la aplicación del asistente podría consultar el estado de un pedido a través de la API del sistema de pedidos. La aplicación que consulta es el cliente; el servicio que recibe la petición y contesta es el servidor.

Cuando esa API utiliza HTTP, el intercambio tiene dos mensajes distintos. La petición indica qué se quiere hacer y a qué recurso se dirige. La respuesta informa del resultado de atender esa petición y, cuando corresponde, devuelve datos. El siguiente vídeo presenta sus piezas principales; no necesitas memorizar todos los métodos que menciona.

Una precisión útil al ver el vídeo: las cabeceras describen el mensaje —por ejemplo, el formato de los datos o la credencial utilizada—, mientras que el cuerpo transporta el contenido de una petición o respuesta cuando lo hay. También puede haber datos en la URL, como veremos enseguida.

Si quieres ver esas piezas expresadas en una referencia técnica breve, lee los apartados indicados de MDN. La representación que muestran se parece a HTTP/1.1; aunque otras versiones transmitan los mensajes de otra forma, aquí nos interesan los mismos conceptos: método, destino, cabeceras, cuerpo y estado.

Lee una petición como una instrucción concreta

Imagina que la aplicación del asistente necesita consultar únicamente el estado del pedido ficticio 4827. Una representación legible de su petición podría ser:

GET /pedidos/4827?campos=estado HTTP/1.1
Host: api.ejemplo.test
Accept: application/json
Authorization: Bearer [credencial omitida]

La dirección y la credencial son ilustrativas; no corresponden a un servicio al que debas conectarte. Podemos leer el mensaje por partes:

• GET es el método. Expresa una solicitud de consulta. No indica, por sí solo, que la persona tenga permiso para consultar cualquier pedido.
• /pedidos/4827 es la ruta del recurso. Identifica qué pedido se solicita dentro del servicio indicado por Host.
• ?campos=estado es un parámetro de consulta de la URL. Pide el campo estado, siempre que esta API admita ese parámetro. La documentación de cada API determina qué parámetros existen y qué significan.
• Accept: application/json es una cabecera. Indica que el cliente acepta una respuesta en formato JSON.
• Authorization es otra cabecera. Aquí representa una credencial omitida deliberadamente. Su presencia no demuestra que la autorización esté bien configurada: el servidor debe comprobarla.

Esta petición no muestra un cuerpo. Es habitual en una consulta GET sencilla. Conviene distinguirlo de «no enviar datos»: el identificador 4827 y el parámetro campos ya viajan en la URL. Por eso no se deben colocar secretos o datos personales innecesarios en parámetros de consulta; las URL pueden quedar registradas o compartirse. Usar HTTPS protege la comunicación en tránsito, pero no elimina la necesidad de controlar accesos y registros.

En cambio, para pedir a una API de IA que genere un borrador, una aplicación podría enviar información en el cuerpo de una petición POST:

POST /borradores-devolucion HTTP/1.1
Host: api.ejemplo.test
Content-Type: application/json
Accept: application/json

{"pedido_id":"4827","instruccion":"Prepara un borrador; no lo envies"}

Aquí Content-Type: application/json describe el formato del cuerpo enviado. POST indica que se remiten datos para una operación; según la API, esa operación podría generar un resultado sin guardarlo o crear un recurso persistente. Ni el método ni el nombre de la ruta bastan para conocer el comportamiento real: hay que contrastarlo con la documentación y la configuración del servicio. Este segundo ejemplo es solo una vista previa; en esta lección nos concentraremos en interpretar el intercambio.

Mira qué muestra —y qué no muestra— un cliente de API

Herramientas como Postman permiten componer una petición y observar la respuesta sin tener que escribir un programa. En el siguiente vídeo, céntrate en leer la pantalla, no en instalar la herramienta ni en reproducir el ejemplo del autor.

Esta otra captura de Postman permite reconocer las mismas zonas de un vistazo:

La zona superior es la petición; la inferior, la respuesta. La pestaña Params organiza los parámetros que también aparecen tras el signo ? en la URL. El 200 OK visible debajo no es un parámetro: es el estado HTTP de la respuesta. Y el texto con llaves bajo JSON es su cuerpo, no la petición que se envió.

En la captura aparecen expresiones como {{spacecraftId}} y {{type}} tanto arriba como en los argumentos mostrados abajo. Son marcadores visibles en este ejemplo: no presupongas que representan valores reales sustituidos. Del mismo modo, ver 200 OK no prueba que un servicio haya devuelto los datos de negocio esperados. Para afirmarlo habría que examinar sus campos y compararlos con lo solicitado.

Lee el resultado: estado HTTP y cuerpo JSON

Volvamos a la consulta ficticia del pedido. Una respuesta posible sería:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "pedido_id": "4827",
  "estado": "entregado",
  "articulos": 2,
  "devolucion": {
    "solicitada": false,
    "motivo": null
  },
  "avisos": []
}

La primera línea indica el código de estado HTTP: 200 OK significa que la petición se atendió correctamente desde el punto de vista HTTP. La cabecera Content-Type anuncia que el cuerpo tiene formato JSON. Tras la línea en blanco empieza ese cuerpo: los datos de la respuesta.

JSON es un formato de texto para representar datos estructurados. Puede incluir objetos con pares clave–valor, listas, textos, números, valores booleanos y null. La lectura de MDN ofrece un ejemplo más amplio y las reglas de sintaxis necesarias para reconocerlo.

Ahora ya puedes recorrer nuestro JSON sin tratarlo como un bloque opaco. Las llaves exteriores delimitan un objeto. Cada clave, como "estado", nombra un dato; el valor situado tras los dos puntos indica su contenido. Las comillas importan:

• "4827" es texto, aunque contenga cifras. En este caso funciona como identificador, no como cantidad con la que calcular.
• "entregado" también es texto; 2, en "articulos": 2, es un número.
• false es un booleano: aquí dice que no consta una devolución solicitada. No es el texto "false".
• null indica ausencia de valor para motivo; no equivale necesariamente a la palabra «ninguno» ni explica por qué falta.
• [] es una lista vacía de avisos.
• "devolucion" contiene otro objeto. Para localizar su dato solicitada, primero entras en devolucion y después lees esa clave.

JSON exige comillas dobles en los nombres de las claves y en los valores de texto. Sin embargo, JSON no define el significado de negocio de cada campo. Que el pedido esté "entregado" no demuestra que sea elegible para devolución; tampoco 200 OK certifica que su estado sea correcto o esté actualizado. Esas conclusiones requieren reglas de negocio, documentación y, cuando proceda, verificación con otras fuentes.

Interpreta los fallos sin adivinar la causa

No todas las respuestas son 200 OK. Una lectura inicial de códigos frecuentes ayuda a decidir qué preguntar cuando una integración falla:

Un código orienta, pero no siempre identifica por sí solo la causa. Además, la respuesta de error puede traer un cuerpo JSON explicativo, otro formato o ningún cuerpo. Si durante un piloto el asistente muestra «pedido inexistente» ante cualquier 404, podría estar afirmando demasiado: el problema quizá sea una ruta mal escrita o una decisión de acceso del servicio.

Para tu función de adopción, la lectura completa combina cuatro preguntas: qué se pidió, qué estado devolvió HTTP, qué datos llegaron realmente y si esos datos permiten realizar la tarea prevista. Así podrás describir una incidencia con precisión: «la consulta del estado recibe 200 OK, pero falta el campo estado» es mucho más útil que «la IA no funciona».

Cierre

Una petición HTTP reúne un método, un destino, posibles cabeceras y, en algunos casos, un cuerpo. La respuesta aporta un código de estado, cabeceras y, cuando corresponde, un cuerpo. Si ese cuerpo es JSON, puedes leer sus claves, valores y estructuras anidadas sin confundir un dato devuelto con una garantía de que sea correcto.

La distinción decisiva es esta: éxito de la comunicación, contenido recibido y valor para la tarea son tres comprobaciones diferentes. En la próxima lección utilizarás esta lectura para ejecutar y adaptar un script guiado en Python que envíe una petición a una API de IA.