En el post anterior nos quedamos con una idea base: una API es una forma ordenada para que un sistema le pida algo a otro sistema.
También vimos que una API no es simplemente una URL. La API es el conjunto de reglas, recursos y formas de comunicación. Las URLs específicas que usamos dentro de esa API normalmente se llaman endpoints.
Hasta ahí vamos bien.
Pero ahora viene la siguiente pregunta natural:
¿Cómo le pido algo a una API?
Porque una cosa es entender que existe una “puerta” para comunicarse con otro sistema, y otra cosa es saber cómo tocar esa puerta correctamente.
Aquí es donde entran los métodos HTTP.
Y sí, suena más técnico.
Pero vamos con calma.
Empecemos con algo que ya conoces
Cuando abres una página en el navegador, normalmente escribes una dirección como esta:
https://jsonplaceholder.typicode.com/postsPresionas Enter y el navegador te muestra una respuesta.
En este caso, JSONPlaceholder te devuelve una lista de publicaciones falsas. No son datos reales de una empresa ni de una red social. Es información de práctica, justo para aprender sin romper nada.
A simple vista parece que solo abriste una URL.
Pero en realidad pasó algo más.
Tu navegador hizo una petición HTTP.
Y, casi siempre que escribes una URL en el navegador y presionas Enter, esa petición usa el método GET.
GET: dame información
GET es el método más fácil de entender porque se parece mucho a lo que hacemos todos los días al navegar por internet.
Cuando haces un GET, básicamente estás diciendo:
Dame esto.Por ejemplo:
GET https://jsonplaceholder.typicode.com/postsEso se podría leer como:
Dame las publicaciones.Otro ejemplo:
GET https://jsonplaceholder.typicode.com/posts/1Eso se podría leer como:
Dame la publicación con ID 1.Aquí ya aparece algo importante. No solo importa la URL completa, también importa qué recurso estás pidiendo.
En JSONPlaceholder, /posts representa publicaciones. Y /posts/1 representa una publicación específica.
No es lo mismo pedir todas las publicaciones que pedir una sola.
La API entiende esa diferencia porque sus endpoints están diseñados con cierta estructura.
El endpoint no trabaja solo
Algo que suele confundir al principio es pensar que el endpoint lo dice todo.
Pero no.
El endpoint es la dirección, pero el método HTTP le da intención a la petición.
Por ejemplo, este endpoint:
https://jsonplaceholder.typicode.com/postspuede tener diferentes significados dependiendo del método que uses.
Si haces:
GET /postsestás diciendo:
Dame las publicaciones.Pero si haces:
POST /postsestás diciendo algo diferente:
Quiero crear una publicación.Mismo recurso.
Diferente intención.
Eso es clave.
Porque una API no solo necesita saber a dónde estás apuntando. También necesita saber qué quieres hacer ahí.
POST: te mando datos
POST se usa normalmente cuando quieres enviar información para crear algo o procesar algo.
Aquí ya no basta con abrir una URL en el navegador.
Y aquí muchos se tropiezan al inicio.
Con GET, normalmente puedes probar desde el navegador porque solo estás pidiendo información. Pero con POST, casi siempre necesitas mandar datos junto con la petición.
Por ejemplo, si quisiéramos crear una publicación en JSONPlaceholder, podríamos hacer una petición como esta:
POST https://jsonplaceholder.typicode.com/postsPero falta algo.
¿Qué publicación queremos crear?
Necesitamos mandar datos. Por ejemplo:
{
"title": "Mi primer post usando una API",
"body": "Estoy aprendiendo cómo se comunican los sistemas.",
"userId": 1
}En cristiano: no solo estás diciendo “quiero crear un post”. También estás diciendo “aquí está el contenido del post”.
Eso es lo que hace que POST tenga más chiste que GET.
Porque ya no solo estás consultando. Estás enviando información para que el otro sistema haga algo con ella.
Pero JSONPlaceholder no guarda de verdad
Aquí vale la pena aclarar algo.
JSONPlaceholder permite probar peticiones como POST, PUT, PATCH y DELETE, pero no modifica datos reales de forma permanente.
Si haces un POST, te va a responder como si hubiera creado el recurso. Eso sirve para practicar y entender el flujo, pero no significa que la publicación quedó guardada en una base de datos real para siempre.
Y eso está perfecto para aprender.
Porque puedes experimentar sin miedo.
Puedes equivocarte.
Puedes mandar mal un dato.
Puedes repetir la petición.
Y no pasa nada grave.
Para este tipo de temas, un laboratorio así vale oro.
PUT: actualiza todo el recurso
Después tenemos PUT.
PUT normalmente se usa para actualizar un recurso completo.
Por ejemplo:
PUT https://jsonplaceholder.typicode.com/posts/1Eso se podría leer como:
Actualiza la publicación con ID 1.Pero cuando usamos PUT, la idea es mandar una versión completa del recurso.
Algo como:
{
"id": 1,
"title": "Título actualizado",
"body": "Contenido actualizado del post.",
"userId": 1
}No es solo “cámbiame una cosita”.
Es más como decir:
Esta es la nueva versión de este recurso.En algunos sistemas esto puede variar un poco, porque no todas las APIs están diseñadas igual. Pero como idea general, PUT se usa cuando quieres reemplazar o actualizar un recurso de forma completa.
PATCH: actualiza una parte
PATCH se parece a PUT, pero tiene una intención más específica.
Con PATCH normalmente quieres actualizar solo una parte del recurso.
Por ejemplo:
PATCH https://jsonplaceholder.typicode.com/posts/1Y podrías mandar solo esto:
{
"title": "Nuevo título"
}Eso se puede leer como:
Deja todo lo demás igual, solo cambia el título.Esa diferencia es útil.
PUT suele representar una actualización más completa.
PATCH suele representar una actualización parcial.
¿Siempre se usa perfecto en todos los proyectos?
No.
Y aquí viene una pequeña verdad de la vida real: no todas las APIs siguen las reglas de forma impecable. A veces encuentras APIs donde PUT y PATCH se usan medio raro, o donde todo lo hacen con POST.
Pero conocer la intención correcta te ayuda a entender mejor lo que estás viendo.
DELETE: elimina algo
DELETE es bastante directo.
Se usa para eliminar un recurso.
Por ejemplo:
DELETE https://jsonplaceholder.typicode.com/posts/1Eso se podría leer como:
Elimina la publicación con ID 1.En un sistema real, esto puede ser delicado. No es lo mismo consultar información que eliminarla.
Por eso muchas APIs protegen este tipo de acciones con permisos, autenticación, validaciones o confirmaciones.
En JSONPlaceholder no pasa nada grave porque es un entorno de práctica. Pero en producción, un DELETE mal usado puede doler.
Y no poquito.
Entonces, ¿los métodos son verbos?
Una forma útil de pensarlo es esta:
El endpoint dice sobre qué recurso quieres trabajar.
El método HTTP dice qué quieres hacer con ese recurso.
Por ejemplo:
GET /posts
POST /posts
GET /posts/1
PUT /posts/1
PATCH /posts/1
DELETE /posts/1Si lo traducimos a lenguaje normal:
Dame las publicaciones.
Crea una publicación.
Dame la publicación 1.
Actualiza la publicación 1.
Cambia una parte de la publicación 1.
Elimina la publicación 1.Eso ya empieza a ordenar mucho el mapa.
No estás memorizando palabras raras. Estás entendiendo intenciones.
Parámetros en la URL
Además del endpoint y el método, muchas APIs permiten mandar parámetros en la URL.
Por ejemplo, JSONPlaceholder permite hacer algo como:
https://jsonplaceholder.typicode.com/posts?userId=1Ese ?userId=1 es un parámetro de consulta, también conocido como query parameter.
Se puede leer así:
Dame las publicaciones del usuario 1.La parte importante es esta:
?userId=1El signo ? indica que a partir de ahí vienen parámetros.
Y si hubiera más de uno, normalmente se separan con &.
Por ejemplo:
/posts?userId=1&status=activeEso se podría leer como:
Dame publicaciones del usuario 1 que estén activas.JSONPlaceholder no usa exactamente ese ejemplo de status, pero sirve para entender la idea.
Los query params son muy comunes para filtrar, buscar, ordenar o limitar resultados.
No todo dato va en la URL
Aquí conviene hacer una pausa.
Hay datos que tiene sentido mandar en la URL, sobre todo cuando estás consultando o filtrando información.
Por ejemplo:
/posts?userId=1Pero hay otros datos que no deberían ir ahí.
Si vas a crear una publicación completa, no sería cómodo ni correcto meter todo el contenido en la URL. Para eso existe otra parte de la petición que veremos con más calma en el siguiente post: el body.
Por ahora quédate con esta idea:
Para consultar o filtrar, muchas veces usas parámetros en la URL.
Para enviar información más completa, normalmente usas el body de la petición.
No lo vamos a desarrollar todavía porque eso merece su propio espacio. Si metemos endpoints, métodos, headers, body y tokens en una sola explicación, terminamos haciendo justo lo que queríamos evitar: aventar todo de golpe.
Cómo probar esto sin escribir código
Una ventaja de usar JSONPlaceholder es que puedes empezar a jugar sin programar demasiado.
Para GET, puedes abrir directamente el navegador:
https://jsonplaceholder.typicode.com/postsO:
https://jsonplaceholder.typicode.com/posts/1Pero para métodos como POST, PUT, PATCH o DELETE, lo normal es usar una herramienta como Postman, Insomnia, Thunder Client o incluso curl.
Por ejemplo, con curl podrías hacer algo como:
curl https://jsonplaceholder.typicode.com/posts/1Eso hace una petición GET.
Para un POST, la petición ya se ve un poco más completa:
curl -X POST https://jsonplaceholder.typicode.com/posts \
-H "Content-Type: application/json" \
-d '{"title":"Mi primer post usando una API","body":"Estoy aprendiendo APIs.","userId":1}'No te preocupes si todavía no entiendes cada parte.
De hecho, ahí ya aparece algo que veremos después: headers, Content-Type y body.
Por ahora lo importante es notar que un POST necesita más información que un GET.
No solo preguntas.
También mandas datos.
Error común: creer que todo es GET
Cuando alguien empieza, es normal pensar que consumir una API es abrir una URL y ya.
Y sí, a veces eso funciona.
Pero solo estás viendo una parte del mundo.
Abrir una URL en el navegador normalmente te permite probar peticiones GET. Eso sirve para consultar información, pero no representa todo lo que una API puede hacer.
Una API también puede recibir datos, crear registros, actualizar información, eliminar recursos o ejecutar procesos.
Por eso existen distintos métodos.
Si todo fuera GET, no habría una forma clara de distinguir entre pedir información y modificar algo.
Y eso sería peligroso.
Imagínate que una URL abierta por accidente eliminara información solo porque alguien la visitó en el navegador.
No suena muy buena idea.
Por eso la intención importa.
Error común: separar endpoint y método como si no tuvieran relación
Otro error común es estudiar endpoints por un lado y métodos HTTP por otro, como si fueran cosas separadas.
En la práctica trabajan juntos.
No basta con saber que existe /posts.
También tienes que saber qué puedes hacer con /posts.
¿Puedes consultarlo?
¿Puedes crear algo ahí?
¿Puedes actualizarlo?
¿Necesitas permisos?
¿Debes mandar datos?
¿La API espera JSON?
Todo eso forma parte de entender cómo se habla con una API.
El endpoint te dice dónde.
El método te dice qué quieres hacer.
Conclusión
En la primera parte entendimos que una API es una forma ordenada para que dos sistemas se comuniquen.
En esta segunda parte vimos cómo empieza esa comunicación.
No basta con tener una URL. Hay que entender qué endpoint estás usando y con qué método HTTP estás haciendo la petición.
GET sirve para pedir información.
POST sirve para enviar datos, normalmente para crear o procesar algo.
PUT suele actualizar un recurso completo.
PATCH suele actualizar una parte.
DELETE sirve para eliminar.
Y aunque al principio parezcan solo palabras técnicas, en realidad son formas de expresar intención.
Eso es lo importante.
Una API no solo necesita saber a dónde estás apuntando.
También necesita saber qué quieres hacer.
En el siguiente post vamos a abrir un poco más la petición por dentro: qué son los headers, qué es el body, cómo se manda JSON y por qué a veces necesitas un token para que la API te haga caso.