HTTP

Resumen

HTTP, Hypertext Transfer Protocol, es el protocolo de nivel de aplicación que gobierna cómo clientes y servidores intercambian información en la web. Cada interacción es un request seguido de un response: el cliente pide un recurso o realiza una acción, y el servidor responde con datos, un código de estado y metadata.

Importa porque casi toda aplicación moderna expone o consume APIs HTTP. Entender sus fundamentos —métodos, códigos de estado, headers, body, statelessness, caching e idempotencia— permite diseñar, depurar y escalar sistemas web sin tratar el protocolo como una caja negra.

Alcance y supuestos

Este paquete cubre HTTP a nivel conceptual: métodos de request, códigos de estado, headers, URIs, cuerpo del mensaje, semántica stateless, negociación de contenido, autenticación vía headers y caching.

No cubre detalles de transporte de HTTP/1.1, HTTP/2 o HTTP/3, diseño completo de APIs REST, ni TLS, DNS o capas inferiores. Asume que entiendes comunicación cliente-servidor, URLs y conceptos básicos de intercambio de datos.

Modelo mental

Piensa en un mesero en un restaurante. El cliente (comensal) hace un pedido: "quiero una ensalada, sin cebolla, con aderezo aparte". El mesero anota el pedido con un formato que la cocina entiende, lo entrega, y vuelve con un plato o con una explicación: "no tenemos ensalada hoy", "aquí está", "el aderezo viene en este recipiente".

HTTP es el idioma y formato que mesero y cocina comparten. El método del request dice qué acción quiere el cliente (GET = tráeme, POST = crea, PUT = reemplaza, DELETE = elimina). Los headers son notas al margen: qué formato acepta, qué tipo de contenido envía, quién es, cuánto tiempo mantener esto en caché. El status code dice qué pasó: 200 = éxito, 404 = no encontrado, 500 = error interno.

La semántica importa más que el transporte. GET no debería cambiar datos del servidor, por más que técnicamente puedas hacerlo. PUT debería ser idempotente: dos llamadas iguales producen el mismo efecto que una. DELETE también. Esto permite reintentar con seguridad cuando una respuesta no llega.

HTTP es stateless: cada request lleva toda la información necesaria. El servidor no recuerda requests anteriores por sí solo. Las sesiones, cookies y tokens de autenticación son capas construidas sobre esa base stateless.

Uso práctico

Entender HTTP te afecta cada vez que diseñas o depuras una API:

• ✅ Elegir el método correcto según semántica: GET para lecturas seguras e idempotentes, POST para crear, PUT para reemplazar, DELETE para eliminar.
• ✅ Interpretar códigos de estado para diagnóstico: 4xx es error del cliente, 5xx es error del servidor, 3xx es redirección, 2xx es éxito.
• ✅ Usar headers para autorización, content type, caching, CORS y negociación de idioma o formato.
• ✅ Diseñar reintentos seguros apoyándote en idempotencia de PUT y DELETE.
• ❌ No ignores los códigos de estado; un 200 con body de error es confuso y rompe tooling HTTP estándar.
• ❌ No uses GET para operaciones con efectos secundarios; navegadores, proxies y crawlers asumen que GET es seguro.

Ejemplo trabajado: leer, crear y reintentar con HTTP semántico

Supón que una aplicación gestiona pedidos vía HTTP. El diseño de la API no es solo estético: afecta reintentos, cachés y diagnóstico.

type Order = {
  id: string;
  customerId: string;
  status: "pending" | "confirmed" | "shipped";
  totalCents: number;
};

// GET — seguro, idempotente, cacheable
async function getOrder(orderId: string): Promise<Order> {
  const response = await fetch(`https://api.example.com/orders/${orderId}`, {
    method: "GET",
    headers: {
      Accept: "application/json",
      Authorization: "Bearer [REDACTED]",
    },
  });

  if (!response.ok) {
    if (response.status === 404) throw new Error("Pedido no encontrado");
    if (response.status === 401) throw new Error("No autorizado");
    throw new Error(`Error inesperado: ${response.status}`);
  }

  return response.json();
}

// POST — no idempotente, crea un recurso nuevo
async function createOrder(order: Omit<Order, "id">): Promise<Order> {
  const response = await fetch("https://api.example.com/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer [REDACTED]",
    },
    body: JSON.stringify(order),
  });

  if (response.status === 201) return response.json();
  if (response.status === 409) throw new Error("Conflicto: pedido duplicado");
  throw new Error(`Error al crear: ${response.status}`);
}

// PUT — idempotente, actualiza el recurso completo
async function updateOrder(orderId: string, order: Order): Promise<Order> {
  const response = await fetch(`https://api.example.com/orders/${orderId}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer [REDACTED]",
    },
    body: JSON.stringify(order),
  });

  if (response.ok) return response.json();
  throw new Error(`Error al actualizar: ${response.status}`);
}

Lo que hace funcionar este diseño:

1. Cada método tiene semántica clara: GET lee, POST crea, PUT reemplaza.
2. Los códigos de estado guían el manejo de errores: 404 no es lo mismo que 401 ni 500.
3. PUT es idempotente: reintentar un update no crea duplicados.
4. POST no es idempotente: reintentar un POST puede crear dos recursos; por eso se chequea 409 Conflict.
5. Los headers comunican tipo de contenido, formato esperado y autenticación.

Antes de diseñar endpoints HTTP, cinco preguntas:

1. ¿Qué método refleja la semántica de esta operación? GET, POST, PUT, DELETE, PATCH.
2. ¿Qué código de estado comunica cada resultado posible? Éxito, error del cliente, error del servidor.
3. ¿Es esta operación idempotente? ¿Qué pasa si el cliente reintenta?
4. ¿Qué headers necesita el request? Content-Type, Accept, Authorization, Cache-Control.
5. ¿Qué headers devuelve el response? Location para recursos creados, Retry-After para rate limiting.

Evidencia

• RFC 9110: HTTP Semantics define HTTP como un protocolo de nivel de aplicación, stateless, para sistemas de información hipertextual distribuidos y colaborativos.
• MDN Web Docs, Overview of HTTP describe HTTP como un protocolo cliente-servidor para obtener recursos, base de todo intercambio de datos en la web.