Tabla de contenido

Cuando hablamos de desarrollo web moderno, las APIs REST están en el centro de casi todo. Son la forma estándar en que las aplicaciones se comunican entre sí: el frontend le habla al backend, las apps móviles obtienen datos del servidor, los sistemas de terceros se integran entre sí. Entender cómo funcionan es fundamental.

¿Qué es una API?

API significa Application Programming Interface (Interfaz de Programación de Aplicaciones). Es un conjunto de reglas que define cómo dos sistemas pueden comunicarse entre sí.

Una analogía: cuando vas a un restaurante, no entras a la cocina a preparar tu comida. Le dices al mesero lo que quieres (haces una petición), él lo lleva a la cocina (el sistema que no ves) y te trae el resultado (la respuesta). El mesero es la API: define el canal de comunicación entre tú y la cocina.

En el mundo del software, la API define qué operaciones puedes pedir, en qué formato envías los datos y qué respuesta puedes esperar.

¿Qué es REST?

REST (Representational State Transfer) es un estilo arquitectónico para diseñar APIs. No es un protocolo ni un estándar rígido, sino un conjunto de principios y restricciones que, cuando se siguen, producen APIs que son simples, escalables y fáciles de entender.

Los principios más importantes de REST son:

Sin estado (Stateless): Cada petición del cliente al servidor debe contener toda la información necesaria para procesarla. El servidor no guarda el estado del cliente entre peticiones.

Interfaz uniforme: Los recursos se identifican por URLs y se manipulan usando los métodos HTTP estándar.

Arquitectura cliente-servidor: El cliente (frontend, app móvil) y el servidor (backend) están completamente separados y se comunican solo a través de la API.

Cacheable: Las respuestas pueden marcarse como cacheables o no para mejorar el rendimiento.

Los métodos HTTP

REST aprovecha los métodos del protocolo HTTP para indicar qué operación quieres hacer sobre un recurso. Los más importantes son:

MétodoOperaciónEjemplo
GETObtener/leer un recursoObtener todos los usuarios
POSTCrear un nuevo recursoRegistrar un nuevo usuario
PUTActualizar un recurso completoActualizar todos los datos de un usuario
PATCHActualizar parcialmente un recursoCambiar solo el email del usuario
DELETEEliminar un recursoBorrar un usuario

La URL identifica el qué (el recurso) y el método HTTP identifica el cómo (la operación). Por ejemplo:

  • GET /usuarios → obtener todos los usuarios
  • POST /usuarios → crear un nuevo usuario
  • GET /usuarios/5 → obtener el usuario con ID 5
  • PUT /usuarios/5 → actualizar completamente el usuario 5
  • DELETE /usuarios/5 → eliminar el usuario 5

Estructura de una petición y respuesta

Una petición HTTP tiene:

  • URL: el endpoint al que se dirige (https://api.ejemplo.com/usuarios)
  • Método: GET, POST, PUT, DELETE…
  • Headers: metadatos de la petición (tipo de contenido, autenticación, etc.)
  • Body: el cuerpo con los datos (en POST y PUT, generalmente en formato JSON)

Ejemplo de petición POST para crear un usuario:

POST /usuarios HTTP/1.1
Host: api.ejemplo.com
Content-Type: application/json
Authorization: Bearer mi-token

{
  "nombre": "Abraham",
  "email": "hola@8devmx.com",
  "ciudad": "Cancún"
}

Una respuesta HTTP tiene:

  • Código de estado: indica si la operación fue exitosa o no (200, 201, 404, 500…)
  • Headers: metadatos de la respuesta
  • Body: los datos devueltos por el servidor (generalmente JSON)

Ejemplo de respuesta:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 42,
  "nombre": "Abraham",
  "email": "hola@8devmx.com",
  "ciudad": "Cancún",
  "created_at": "2026-03-08T10:30:00Z"
}

Códigos de estado HTTP

Los códigos de estado son números de 3 dígitos que indican el resultado de la petición. Están agrupados por categorías:

2xx - Éxito:

  • 200 OK: petición exitosa
  • 201 Created: recurso creado exitosamente
  • 204 No Content: exitoso pero sin contenido para devolver

3xx - Redirección:

  • 301 Moved Permanently: el recurso se movió a otra URL

4xx - Error del cliente:

  • 400 Bad Request: la petición tiene datos mal formados
  • 401 Unauthorized: no estás autenticado
  • 403 Forbidden: estás autenticado pero no tienes permiso
  • 404 Not Found: el recurso no existe
  • 422 Unprocessable Entity: los datos son válidos pero no pueden procesarse

5xx - Error del servidor:

  • 500 Internal Server Error: error interno del servidor
  • 503 Service Unavailable: el servicio no está disponible

Un ejemplo completo

Para entender todo esto en contexto, veamos cómo JavaScript puede consumir una API REST usando Fetch:

// GET - Obtener todos los usuarios
async function obtenerUsuarios() {
  const respuesta = await fetch("https://api.ejemplo.com/usuarios", {
    headers: {
      "Authorization": "Bearer mi-token"
    }
  });
  const usuarios = await respuesta.json();
  console.log(usuarios);
}

// POST - Crear un usuario
async function crearUsuario(datos) {
  const respuesta = await fetch("https://api.ejemplo.com/usuarios", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer mi-token"
    },
    body: JSON.stringify(datos)
  });
  
  if (respuesta.status === 201) {
    const nuevoUsuario = await respuesta.json();
    console.log("Usuario creado:", nuevoUsuario);
  } else {
    console.error("Error:", respuesta.status);
  }
}

// DELETE - Eliminar un usuario
async function eliminarUsuario(id) {
  const respuesta = await fetch(`https://api.ejemplo.com/usuarios/${id}`, {
    method: "DELETE",
    headers: { "Authorization": "Bearer mi-token" }
  });
  
  if (respuesta.status === 204) {
    console.log("Usuario eliminado exitosamente");
  }
}

¿JSON o XML?

En el pasado, muchas APIs usaban XML para estructurar sus datos. Hoy en día, el estándar de facto es JSON (JavaScript Object Notation) por varias razones:

  • Es más ligero y fácil de leer que XML
  • JavaScript lo puede parsear nativamente con JSON.parse()
  • La mayoría de lenguajes modernos tienen soporte nativo o librerías para JSON
  • Es más sencillo de escribir y debuggear

Entender cómo funcionan las APIs REST es una habilidad que usarás prácticamente en todos los proyectos que hagas, ya sea consumiendo APIs de terceros (pagos, mapas, redes sociales) o construyendo las tuyas propias con PHP, Node.js u otro lenguaje backend.