¿Qué es una API REST y Cómo Usar Métodos HTTP GET, POST, PUT, DELETE?
Domina los principios del estilo arquitectónico REST, las operaciones CRUD mapeadas a verbos HTTP, las buenas prácticas de diseño de URIs y el principio de no almacenamiento de estado.
Una API REST (Representational State Transfer) es un estilo de arquitectura de software para sistemas hipermedia distribuidos, basado en la utilización de los métodos nativos del protocolo HTTP y recursos identificados mediante URLs sin conservar estado en el servidor (stateless).
Estandariza la forma en que los clientes realizan operaciones CRUD (Crear, Leer, Actualizar, Borrar), permitiendo que cualquier plataforma (móvil, web o IoT) interactúe con el servidor con reglas predecibles y alta capacidad de escalabilidad.
Imagina una biblioteca pública con reglas estrictas: cada libro tiene un código único en la estantería (URI). Para leerlo usas la tarjeta verde (GET), para donar un libro nuevo usas la tarjeta azul (POST), para reemplazar una edición dañada por una nueva usas la amarilla (PUT), y para retirar un libro obsoleto del catálogo usas la tarjeta roja (DELETE).
Explicación Paso a Paso del Tema
Mapear operaciones CRUD a los métodos HTTP correctos
Aprende el estándar universal de correspondencia entre acciones de datos y verbos HTTP.
Create -> POST (crea un nuevo recurso hijo en la colección). Read -> GET (recupera la representación de uno o varios recursos). Update -> PUT (reemplaza por completo el recurso existente) o PATCH (modifica solo campos específicos). Delete -> DELETE (elimina el recurso indicado en la URL).
GET /usuarios (listar) | POST /usuarios (crear) | GET /usuarios/5 (ver) | PUT /usuarios/5 (reemplazar) | DELETE /usuarios/5 (borrar)
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| GET /usuarios | Lectura masiva | Devuelve un arreglo con la lista de usuarios paginada |
| POST /usuarios | Creación | Genera una nueva entidad y asigna un ID único |
| DELETE /usuarios/5 | Eliminación | Destruye el registro correspondiente al identificador 5 |
Usa siempre sustantivos en plural para las colecciones (ej. /articulos, /pedidos, /clientes) para mantener total coherencia en tu API.
Crear URLs con verbos de acción como '/api/borrarUsuario?id=5' o '/api/crearNuevoProducto'. En REST la URL representa el sustantivo y el método HTTP indica la acción.
Distinguir la diferencia entre PUT y PATCH
Aplica PUT para sobrescritura total del recurso y PATCH para actualizaciones parciales.
Si un usuario tiene nombre, correo y teléfono, enviar un PUT con solo `{"telefono":"1234"}` obligaría al servidor según la especificación REST a borrar o dejar nulos el nombre y correo no especificados. Si deseas cambiar únicamente el teléfono conservando el resto intacto, el método adecuado es PATCH.
curl -X PATCH https://api.tienda.com/productos/99 -H "Content-Type: application/json" -d '{"stock": 15}'| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| -X PATCH | Método HTTP | Aplica modificaciones parciales a un recurso existente |
| -d '{"stock": 15}' | JSON Delta | Solo contiene los atributos exactos que sufren variación |
Documenta explícitamente en OpenAPI/Swagger si tu endpoint acepta payloads parciales mediante PATCH.
Usar PUT cuando en realidad se programa lógica de PATCH en el servidor, confundiendo a los clientes de la API sobre la idempotencia del contrato.
Configurar códigos de respuesta semánticos
Responde con el código de estado HTTP exacto según el resultado de la operación.
Una API REST bien diseñada nunca devuelve 200 OK cuando hubo un error. Si un recurso se creó exitosamente responde con 201 Created. Si una petición no contiene cuerpo devuelve 204 No Content. Si el cliente envió campos faltantes o inválidos devuelve 400 Bad Request. Si no tiene autorización devuelve 401 Unauthorized.
HTTP/1.1 201 Created -> Encabezado: Location: /v1/pedidos/88219
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| 201 Created | Código de éxito | Confirma que la petición fue procesada y se materializó un nuevo recurso en la base de datos |
| Location | Header de respuesta | Indica la URL directa donde el cliente puede consultar el nuevo recurso creado |
Sigue el estándar RFC 7807 (Problem Details for HTTP APIs) para estructurar respuestas de error consistentes con tipo, título, detalle y código de error.
Devolver '200 OK' con un cuerpo que dice `{"error": "Usuario no encontrado"}`. Esto rompe la integración con clientes automatizados.
Casos Prácticos Reales en Producción
Situaciones de ingeniería reales sin mención de presupuestos ficticios.
1Caso de Producción: Estandarización de API para Catálogo de Inventario Multinacional
Una empresa de retail tenía más de 80 endpoints caóticos con nombres como /get_all_items, /doDeleteProduct, y /updatePriceNow, lo que provocaba bugs continuos y duplicación de código en sus apps de iOS, Android y Web.
Se refactorizó el catálogo hacia una arquitectura RESTful pura: colección unificada `/v1/productos` gobernada por verbos GET, POST, PUT, PATCH y DELETE, acompañada de documentación viva generada mediante OpenAPI.
Fichas Nemotécnicas de Conceptos Clave
Glosario rápido para recordar los términos fundamentales de la lección.
Principio clave de REST donde cada petición del cliente debe contener toda la información requerida para ser procesada, sin que el servidor deba retener sesiones previas.
Propiedad de una operación HTTP donde ejecutarla una o múltiples veces produce exactamente el mismo efecto en el estado del servidor.
Cualquier objeto, entidad o documento accesible mediante un identificador uniforme (URI), nombrado con sustantivos en plural.
¿Qué es una API REST y Cómo Usar Métodos HTTP GET, POST, PUT, DELETE?
Selecciona una opción para autoevaluarte al instante. La respuesta se califica de inmediato.
¿Cuál de las siguientes URLs cumple de manera más fiel las buenas prácticas REST?
¿Qué código de estado HTTP debe devolver el servidor tras crear con éxito un nuevo recurso?
¿Cuál es la diferencia principal entre PUT y PATCH?
Preguntas Frecuentes (FAQ)
¿Es GraphQL mejor que REST?
No es intrínsecamente mejor, son enfoques distintos. REST es excelente por su simplicidad, caché nativo HTTP y madurez universal. GraphQL destaca cuando el cliente necesita solicitar campos específicos y anidados en una sola consulta para evitar over-fetching.
¿Por qué las URLs de recursos REST deben estar en plural?
Porque representan colecciones lógicas de entidades (ej. `/clientes`). `/clientes/12` se lee naturalmente como: 'de la colección de clientes, dame el que tiene identificador 12'.
¿Qué significa que REST sea Stateless?
Significa que el servidor no recuerda al cliente entre peticiones a través de sesiones en memoria local; cada llamada debe incluir su propia credencial (token) para autenticarse de forma autónoma.