En la parte anterior vimos que no basta con tener una URL para hablar con una API.
También importa el método.
No es lo mismo hacer un GET /posts que un POST /posts. El endpoint puede ser el mismo, pero la intención cambia. Uno pide información. El otro manda datos para crear o procesar algo.
Hasta ahí ya tenemos dos piezas importantes:
Endpoint: a dónde le estoy pegando.
Método: qué quiero hacer ahí.Pero una petición a una API casi nunca se queda solo en eso.
Cuando empiezas a usar APIs en proyectos reales, rápido aparecen más preguntas:
¿Qué datos estoy mandando?
¿En qué formato van?
¿Cómo le digo a la API que estoy enviando JSON?
¿Cómo sabe la API quién soy?
¿Dónde va el token?
Ahí entran conceptos como headers, body, Content-Type, Authorization y JSON.
Y sí, al principio parecen muchas cosas.
Pero vamos por partes.
Primero: ¿qué es una petición?
Una petición, o request, es el mensaje que tu aplicación le manda a la API.
En cristiano: es la forma en la que tu sistema dice:
Quiero hacer esto.
Aquí está lo que necesitas para hacerlo.Por ejemplo, si solo quieres consultar una publicación en JSONPlaceholder, la petición puede ser muy simple:
GET https://jsonplaceholder.typicode.com/posts/1Ahí estás diciendo:
Dame la publicación con ID 1.Pero si quieres crear una publicación, la petición necesita más información:
POST https://jsonplaceholder.typicode.com/postsEso dice la intención general, pero todavía falta el contenido.
¿Qué publicación quieres crear?
Ahí entra el body.
El body: los datos que mandas
El body es el cuerpo de la petición.
Es donde normalmente mandas la información que quieres enviar a la API.
Por ejemplo, si queremos crear una publicación en JSONPlaceholder, podríamos mandar algo así:
{
"title": "Aprendiendo APIs",
"body": "Estoy entendiendo qué lleva una petición.",
"userId": 1
}Ese JSON representa los datos de la publicación.
El título.
El contenido.
El usuario al que pertenece.
Entonces, una petición POST completa no solo dice:
Quiero crear una publicación.También dice:
Y estos son los datos de esa publicación.Esto es una diferencia importante con GET.
En un GET, normalmente pides información.
En un POST, muchas veces mandas información para que la API haga algo con ella.
No todo va en el body
Aquí vale la pena hacer una pausa.
No todos los datos se mandan en el body.
A veces mandas datos en la URL usando query params, como vimos en la parte anterior:
https://jsonplaceholder.typicode.com/posts?userId=1Eso se puede leer como:
Dame las publicaciones del usuario 1.Ese userId=1 va en la URL porque funciona como un filtro.
En cambio, si vas a crear una publicación completa, no tendría mucho sentido meter todo el título y el contenido en la URL. Para eso usamos el body.
Una forma sencilla de pensarlo es esta:
Query params: filtros o detalles para consultar.
Body: datos más completos que quiero enviar.No es una regla absoluta para todos los casos del mundo, pero como modelo inicial funciona bastante bien.
JSON: el formato que vas a ver muchas veces
Cuando mandamos datos a una API, necesitamos usar un formato que ambos lados entiendan.
Uno de los formatos más comunes es JSON.
JSON se ve así:
{
"title": "Aprendiendo APIs",
"body": "Estoy entendiendo qué lleva una petición.",
"userId": 1
}Si lo ves con calma, no es tan extraño.
Tiene claves y valores.
"title": "Aprendiendo APIs"La clave es title.
El valor es "Aprendiendo APIs".
Otro ejemplo:
"userId": 1La clave es userId.
El valor es 1.
JSON puede tener textos, números, valores verdaderos o falsos, listas y objetos anidados. Pero no necesitamos meter todo eso de golpe.
Por ahora basta con entender que JSON es una forma ordenada de representar datos.
Y muchas APIs lo usan para recibir y responder información.
Pero la API necesita saber qué le estás mandando
Aquí entra un detalle importante.
No basta con mandar JSON.
También tienes que decirle a la API que lo que estás mandando es JSON.
¿Y dónde se dice eso?
En los headers.
Headers: información adicional de la petición
Los headers son datos adicionales que acompañan la petición.
No son el contenido principal como tal, pero le dan contexto a la API.
Es como decir:
Te estoy mandando esta petición.
Y además te aviso estas cosas importantes.Por ejemplo, cuando mandas JSON, normalmente incluyes este header:
Content-Type: application/jsonEso le dice a la API:
El contenido que te estoy mandando viene en formato JSON.Sin ese header, algunas APIs podrían no entender correctamente el body. O podrían rechazar la petición porque no saben cómo interpretar los datos.
En JSONPlaceholder muchas cosas funcionan aunque no seas tan estricto, porque está hecho para practicar. Pero en APIs reales, estos detalles sí importan.
Y mucho.
Content-Type: el formato del contenido
Content-Type es uno de los headers más comunes.
Sirve para indicar el tipo de contenido que estás enviando.
Por ejemplo:
Content-Type: application/jsonSignifica:
Estoy enviando JSON.Pero podrían existir otros tipos de contenido, como formularios, archivos o texto plano.
No necesitamos entrar en todos ahora.
Para esta serie, lo importante es que cuando mandes JSON en el body, normalmente debes acompañarlo con:
Content-Type: application/jsonEs una de esas cosas que al principio parecen detalle menor, pero luego explican muchos errores.
Porque a veces el body está bien, el endpoint está bien y el método está bien, pero la API no interpreta lo que mandaste porque faltó o estuvo mal el Content-Type.
Y ahí uno puede perder tiempo buscando el problema donde no era.
Authorization: quién eres y si tienes permiso
Otro header muy común es Authorization.
Este sirve para enviar credenciales o tokens de acceso.
Por ejemplo:
Authorization: Bearer <TOKEN>En español simple, eso le dice a la API:
Aquí está mi token.
Con esto puedes validar quién soy o si tengo permiso.No todas las APIs públicas necesitan token.
JSONPlaceholder, por ejemplo, no lo necesita para practicar.
Pero en sistemas reales casi siempre hay algún tipo de autenticación. No tendría sentido que cualquiera pudiera consultar datos privados, crear registros, eliminar información o ejecutar acciones delicadas sin identificarse.
Por eso muchas APIs piden un token.
El token funciona como una especie de pase temporal. La API lo revisa y decide si puedes hacer lo que estás intentando hacer.
Si el token es válido, te deja pasar.
Si no existe, está mal o ya venció, probablemente te responderá con un error.
Eso lo veremos con más calma en la siguiente parte, cuando hablemos de respuestas y códigos de estado.
Una petición completa
Juntando todo, una petición POST a JSONPlaceholder podría verse así:
curl -X POST https://jsonplaceholder.typicode.com/posts \
-H "Content-Type: application/json" \
-d '{
"title": "Aprendiendo APIs",
"body": "Estoy entendiendo qué lleva una petición.",
"userId": 1
}'Vamos a leerla con calma.
curlEs una herramienta para hacer peticiones desde la terminal.
-X POSTIndica que queremos usar el método POST.
https://jsonplaceholder.typicode.com/postsEs el endpoint.
-H "Content-Type: application/json"Es un header que dice que estamos enviando JSON.
-d '{ ... }'Es el body, es decir, los datos que estamos mandando.
Si lo traducimos a lenguaje normal, la petición dice algo como:
Quiero crear una publicación en /posts.
Te mando los datos en formato JSON.
Aquí está el título, el contenido y el usuario.Eso ya empieza a verse más completo.
No es magia.
Es una petición con piezas bien definidas.
¿Y si lo quiero probar sin terminal?
También se puede usar Postman, Insomnia o Thunder Client.
En una herramienta visual normalmente eliges:
Método: POST
URL: https://jsonplaceholder.typicode.com/posts
Header: Content-Type: application/json
Body: JSON con los datosY luego presionas Send.
La ventaja de estas herramientas es que puedes ver la petición más ordenada. Puedes separar headers, body, parámetros y respuesta sin tener que escribir todo a mano.
La terminal está muy bien, pero cuando estás aprendiendo, una herramienta visual puede ayudarte a entender qué va en cada lugar.
Lo importante no es casarse con una herramienta.
Lo importante es entender las piezas.
Error común: mandar todo en la URL
Un error común cuando uno empieza es querer mandar todo en la URL.
Por ejemplo, algo así:
/posts?title=Aprendiendo APIs&body=Estoy entendiendo...Para filtros simples puede estar bien usar query params.
Pero para enviar información más completa, especialmente en POST, lo normal es usar el body.
La URL debería ayudar a identificar el recurso o aplicar filtros.
El body debería llevar los datos principales que quieres crear, actualizar o procesar.
De nuevo, puede haber excepciones.
Pero como punto de partida, esta separación ayuda mucho.
Error común: olvidar los headers
Otro error común es mandar un body correcto, pero sin headers.
El JSON puede estar bien escrito. El endpoint puede ser el correcto. El método puede ser POST. Pero si la API espera que le digas explícitamente que estás enviando JSON y no lo haces, puede fallar.
A veces el error se ve raro.
A veces parece que “la API no sirve”.
Pero en realidad la API sí está funcionando. El problema es que la petición no venía bien formada.
Esto pasa mucho al inicio.
Y no pasa nada.
Parte de aprender APIs es entender que los detalles de la petición importan.
Error común: confundir autenticación con formato
También pasa que alguien ve un error y piensa que el JSON está mal, cuando en realidad falta el token.
O al revés: piensa que el token está mal, pero el problema era el Content-Type.
Por eso conviene ordenar mentalmente las piezas.
Cuando una petición falla, puedes preguntarte:
¿Estoy usando el endpoint correcto?
¿Estoy usando el método correcto?
¿Estoy mandando los datos donde van?
¿El body tiene el formato esperado?
¿Mandé el Content-Type?
¿Necesito Authorization?No siempre vas a resolverlo a la primera.
Pero ya no estás adivinando a ciegas.
Una API necesita contexto
Si algo me gustaría que quedara claro en esta parte es esto:
Una API no solo recibe una URL.
Recibe una petición completa.
Y esa petición puede traer método, endpoint, parámetros, headers, body y credenciales.
Cada pieza le da contexto a la API para entender qué quieres hacer y si puede hacerlo.
Por eso dos peticiones al mismo endpoint pueden comportarse diferente.
No es lo mismo:
GET /postsque:
POST /postsY tampoco es lo mismo un POST con body que un POST vacío.
Ni un POST con Content-Type correcto que uno mal formado.
La API toma decisiones con base en todo lo que le mandas.
Conclusión
En la parte anterior vimos que el método HTTP le da intención a la petición.
En esta parte abrimos un poco más esa petición por dentro.
Vimos que el body sirve para mandar datos, que JSON es uno de los formatos más comunes, que los headers agregan contexto y que Content-Type y Authorization suelen ser claves en APIs reales.
No hace falta memorizar todo de golpe.
Pero sí conviene entender la idea:
El endpoint dice a dónde voy.
El método dice qué quiero hacer.
Los headers dan contexto.
El body lleva los datos.
El token ayuda a demostrar quién soy o qué permiso tengo.Cuando juntas esas piezas, empiezas a dejar de copiar peticiones sin entenderlas.
Y eso cambia mucho.
Porque ya no estás solo “probando una API”.
Estás entendiendo cómo se construye la conversación.
En la siguiente parte vamos a ver el otro lado: qué responde una API, cómo leer códigos como 200, 201, 400, 401, 403, 404 o 500, y por qué no todos los errores significan lo mismo.