API REST explicada fácil: qué es, cómo funciona y ejemplo práctico

Entiende qué es una API REST, cómo funciona con HTTP y JSON, sus métodos y códigos, mediante un ejemplo práctico explicado paso a paso.

Una API permite que dos programas intercambien información o soliciten acciones mediante una interfaz definida. REST es un estilo arquitectónico para sistemas distribuidos; no es un lenguaje, un protocolo ni un sinónimo de JSON. Cuando una API utiliza HTTP y organiza su interfaz alrededor de recursos siguiendo ideas de REST, normalmente hablamos de una API REST o RESTful.

La distinción importa porque evita aprender una lista de recetas sin comprender qué ocurre entre cliente y servidor. Si todavía te cuesta separar ambas partes de una aplicación, empieza por nuestra guía sobre las diferencias entre frontend y backend.

¿Qué es una API REST en palabras simples?

Imagina una aplicación que muestra el inventario de una tienda. La interfaz del usuario necesita consultar productos, ver uno concreto, registrar un pedido o actualizar una cantidad. En lugar de conectarse directamente a la base de datos, puede comunicarse con un servicio mediante una API.

Una petición podría dirigirse a un recurso como:

GET /productos/42

El servidor interpreta la solicitud y devuelve una respuesta. Si todo salió bien, podría responder con datos del producto y un código HTTP que describa el resultado.

La API define qué puede pedir el cliente, cómo debe pedirlo y qué respuestas puede esperar. La implementación interna —base de datos, lenguaje, servicios o reglas de negocio— puede cambiar sin obligar al cliente a conocer todos esos detalles, siempre que el contrato de la interfaz se conserve.

API, REST y RESTful: no son lo mismo

API es un concepto amplio: una interfaz para que software se comunique con otro software.

REST —Representational State Transfer— es el estilo arquitectónico descrito por Roy Fielding para sistemas hipermedia distribuidos. Entre sus restricciones aparecen cliente-servidor, comunicación sin estado, posibilidad de caché, interfaz uniforme y sistema por capas. El código bajo demanda es opcional.

RESTful suele usarse para describir un sistema que aplica esas restricciones. En la práctica, muchas APIs se llaman “REST” porque utilizan HTTP, recursos y métodos como GET o POST aunque no implementen cada aspecto del modelo de Fielding. Por eso conviene tratar “RESTful” como una descripción arquitectónica, no como un sello automático.

Cómo funciona una API REST entre cliente y servidor

Una interacción HTTP básica tiene cuatro piezas fáciles de reconocer:

Método: expresa la semántica de la solicitud, por ejemplo GET, POST, PUT, PATCH o DELETE.
URI o URL objetivo: identifica el recurso al que se dirige la petición.
Cabeceras y, cuando corresponde, contenido: pueden indicar autenticación, tipo de representación, preferencias y datos enviados.
Respuesta: incluye un código de estado, cabeceras y, cuando aplica, una representación del resultado.

Por ejemplo, una aplicación podría consultar:

GET /api/productos/42 HTTP/1.1
Host: ejemplo.test
Accept: application/json

Y recibir:

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

{
  "id": 42,
  "nombre": "Teclado USB",
  "disponible": true
}

El ejemplo es ficticio: sirve para entender el flujo, no representa una API pública de Crezendo.

Recursos y endpoints

En REST se piensa principalmente en recursos: productos, pedidos, usuarios, documentos u otras entidades que una aplicación necesita representar y manipular.

Una interfaz coherente puede usar rutas como:

/productos
/productos/42
/pedidos
/pedidos/830

En documentación de APIs se usa mucho la palabra endpoint para referirse a un punto concreto de interacción, normalmente combinando una ruta con una operación. Por ejemplo, GET /productos/42 y DELETE /productos/42 actúan sobre la misma URI pero tienen semánticas diferentes.

No necesitas llenar las rutas de verbos como /obtenerProducto o /borrarProducto. HTTP ya dispone de métodos con semántica definida y una API orientada a recursos suele ser más fácil de comprender cuando las rutas representan sustantivos.

Métodos HTTP: GET, POST, PUT, PATCH y DELETE

Los métodos no son simples nombres arbitrarios. HTTP define su semántica y propiedades como seguridad o idempotencia.

Método	Uso habitual	Idea importante
`GET`	Obtener una representación	Está definido como método seguro; no debería solicitar un cambio de estado del recurso.
`POST`	Enviar datos para que el recurso los procese	Puede crear un recurso, iniciar una operación u obtener otro resultado según la API.
`PUT`	Crear o reemplazar el estado del recurso identificado	Su semántica es idempotente: repetir la misma petición pretende tener el mismo efecto final.
`PATCH`	Aplicar una modificación parcial	Fue definido específicamente como método de modificación parcial; el formato del parche depende de la API.
`DELETE`	Solicitar que se elimine la asociación del recurso objetivo	También está definido como idempotente, aunque respuestas sucesivas puedan diferir.

Una simplificación común es enseñar POST = crear y PUT = editar. Puede servir como primer mapa mental, pero no sustituye la semántica real de HTTP. El contrato concreto de cada API debe documentar qué acepta y qué produce.

JSON es frecuente, pero REST no obliga a usarlo

JSON es un formato de intercambio de datos ligero, textual e independiente del lenguaje. Es muy común en APIs web porque resulta sencillo de producir y consumir, pero REST no exige JSON.

Una representación podría ser JSON, HTML, XML, texto, una imagen u otro formato que tenga sentido para el recurso y que cliente y servidor sepan manejar. HTTP permite negociar y declarar tipos de contenido mediante cabeceras como Accept y Content-Type.

Ejemplo JSON:

{
  "id": 830,
  "estado": "pendiente",
  "total": 24.50
}

La estructura exacta no la decide REST; la define el contrato de esa API.

Códigos de estado HTTP que debes reconocer

El código de estado resume el resultado de la petición. Algunos de los más útiles al empezar son:

200 OK: la operación tuvo éxito y la respuesta contiene el resultado correspondiente.
201 Created: la petición produjo la creación de uno o más recursos.
204 No Content: la operación tuvo éxito y no se envía contenido de respuesta.
400 Bad Request: el servidor considera que la solicitud tiene un problema del lado del cliente.
401 Unauthorized: faltan credenciales de autenticación válidas para el recurso.
403 Forbidden: el servidor entendió la petición, pero rechaza autorizarla.
404 Not Found: no se encontró una representación actual del recurso objetivo o el servidor no desea revelar que existe.
409 Conflict: la petición entra en conflicto con el estado actual del recurso.
500 Internal Server Error: el servidor encontró una condición inesperada que impide completar la solicitud.

Evita responder 200 a todo y colocar el error únicamente dentro del JSON. Usar correctamente la semántica HTTP facilita que clientes, proxies, observabilidad y herramientas de prueba entiendan lo sucedido.

Ejemplo práctico: una API de inventario

Supongamos una tienda ficticia que expone estas operaciones:

GET    /productos
GET    /productos/42
POST   /pedidos
PATCH  /pedidos/830
DELETE /pedidos/830

1. Consultar un producto

GET /productos/42

Respuesta posible:

{
  "id": 42,
  "nombre": "Teclado USB",
  "stock": 7
}

2. Crear un pedido

POST /pedidos
Content-Type: application/json

{
  "producto_id": 42,
  "cantidad": 2
}

Si el servidor crea el pedido, podría devolver 201 Created, una cabecera Location con la URI del nuevo recurso y una representación del pedido.

3. Modificar una parte del pedido

PATCH /pedidos/830
Content-Type: application/json

{
  "cantidad": 3
}

El servidor debe documentar qué formato acepta para el cambio parcial. PATCH no significa que cualquier objeto JSON sea automáticamente un parche válido.

Este ejercicio ya permite practicar rutas, métodos, cuerpos, tipos de contenido, códigos de estado y manejo de errores sin depender de un framework específico.

Qué significa que REST sea “sin estado”

La restricción stateless indica que cada solicitud del cliente debe contener la información necesaria para que el servidor la comprenda; el servidor no puede depender de contexto de sesión almacenado entre solicitudes para interpretar el mensaje.

Eso no significa que el servidor “no guarde estado”. Una base de datos puede guardar usuarios, pedidos, permisos y cualquier otro estado de la aplicación. Lo que REST limita es el estado de la sesión de interacción que el servidor necesitaría recordar entre una petición y la siguiente.

Tampoco significa automáticamente “más rápido”. Las restricciones arquitectónicas producen determinados compromisos y propiedades; el rendimiento final depende del diseño, la infraestructura, la caché, la base de datos y muchos otros factores.

REST no es solamente HTTP + JSON

Para aprender bien, evita estas equivalencias:

REST = HTTP: REST es un estilo arquitectónico; HTTP es un protocolo con semántica propia.
REST = JSON: JSON es sólo un formato posible de representación.
REST = CRUD: crear, leer, actualizar y eliminar es un patrón útil, pero no define por sí solo REST.
endpoint = tabla: una API no tiene por qué exponer directamente la estructura de la base de datos.
stateless = sin datos persistentes: el servidor puede persistir estado de recursos sin mantener contexto de sesión entre peticiones.

Comprender esas diferencias hace más fácil leer documentación real y detectar diseños inconsistentes.

Errores frecuentes al diseñar o consumir una API REST

Ignorar los códigos de estado: un cliente robusto no debería asumir que toda respuesta es exitosa.
Confundir autenticación con autorización: demostrar quién eres no implica tener permiso para cada operación.
Enviar secretos en URLs: las credenciales y tokens requieren mecanismos apropiados; no deben aparecer casualmente en parámetros que puedan terminar en historiales o logs.
No validar datos: el servidor debe tratar la entrada del cliente como no confiable.
Romper el contrato sin versión o estrategia de migración: cambiar campos o significado puede afectar consumidores existentes.
Usar métodos sólo por comodidad: semántica, idempotencia, caché y herramientas intermedias dependen de esas decisiones.
Asumir que una respuesta JSON válida equivale a una operación correcta: también debes comprobar estado HTTP y reglas de negocio.

Cómo practicar sin memorizar definiciones

Una ruta útil para principiantes es construir primero una API mínima con cuatro o cinco operaciones y probarla desde curl, el navegador cuando corresponda o una herramienta cliente. Después agrega validación, autenticación, paginación, filtros y manejo consistente de errores.

Conviene poder responder estas preguntas sobre cada operación:

¿Qué recurso estoy representando?
¿Qué método expresa mejor la intención?
¿Qué datos recibe la solicitud?
¿Qué código y representación devuelve cuando funciona?
¿Qué errores puede producir?
¿La operación es segura o idempotente según HTTP?
¿Qué necesita saber un cliente para usarla sin conocer la implementación interna?

Ese razonamiento vale más que memorizar que “GET lee y POST crea”.

Fuentes técnicas

Roy Fielding, capítulo 5 de su tesis sobre REST: restricciones y propiedades del estilo arquitectónico REST.
RFC 9110 — HTTP Semantics: métodos, códigos de estado y semántica HTTP vigente.
RFC 5789 — PATCH Method for HTTP: definición del método PATCH.
RFC 8259 — JSON: especificación del formato JSON.

Si estás evaluando una capacitación práctica para tu equipo o necesitas orientación sobre una ruta de aprendizaje técnico, puedes contactar a Crezendo y explicar qué conocimientos quieren desarrollar.