jQuery AJAX: guía práctica de peticiones asíncronas, desde los ejemplos básicos hasta la gestión de errores

AJAX permite que una página web se comunique con el servidor sin recargarla por completo. Con jQuery sigue siendo útil en proyectos existentes, paneles administrativos y aplicaciones que ya dependen de la biblioteca. El navegador envía una petición HTTP, recibe datos —a menudo JSON— y actualiza solo la zona necesaria.

La documentación oficial define $.ajax() como el motor de las peticiones Ajax de jQuery. $.get(), $.post(), $.getJSON() y .load() simplifican casos comunes; $.ajax() controla método, cabeceras, tiempo de espera, formato y errores.

Cargar la versión correcta de jQuery

En el momento de redactar esta guía, el proyecto indica jQuery 4.0.0 como versión estable. AJAX necesita la compilación completa: la versión slim excluye Ajax y efectos. En producción conviene usar el archivo minificado y Subresource Integrity si se carga desde CDN.

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>

Primera petición con $.ajax()

$.ajax({
  url: "/api/posts",
  method: "GET",
  dataType: "json",
  timeout: 10000
})
.done(function (data) { console.log(data); })
.fail(function (jqXHR, textStatus, errorThrown) {
  console.error("La petición falló:", textStatus, errorThrown);
})
.always(function () { console.log("Petición finalizada"); });

url identifica el recurso, method el verbo HTTP y dataType el formato esperado. El tiempo de espera se expresa en milisegundos y comienza cuando se llama a $.ajax().

jqXHR y ejecución asíncrona

$.ajax() devuelve un objeto jqXHR que implementa la interfaz Promise de jQuery. Se recomiendan .done(), .fail(), .always() y .then(). Los antiguos .success(), .error() y .complete() se eliminaron en jQuery 3.0.

const request = $.ajax({ url: "/api/search", data: { q: "ajax" } });
$("#cancel").on("click", function () { request.abort(); });

GET, POST y serialización

Cuando data es un objeto, jQuery suele convertirlo en una cadena de consulta mediante jQuery.param().

$.get("/api/search", { q: "jquery", page: 1 })
  .done(function (results) { renderResults(results); });

Un formulario tradicional puede enviarse con .serialize():

$("#contact-form").on("submit", function (event) {
  event.preventDefault();
  $.post("/api/contact", $(this).serialize())
    .done(function () { $("#message").text("Mensaje enviado"); })
    .fail(showRequestError);
});

Para una API JSON, serializa el cuerpo y declara el tipo:

$.ajax({
  url: "/api/users",
  method: "POST",
  contentType: "application/json; charset=UTF-8",
  dataType: "json",
  data: JSON.stringify({ name: "Ada", role: "editor" })
});

contentType describe lo enviado; dataType describe la respuesta esperada.

Errores HTTP y mensajes útiles

Una interfaz robusta distingue validación, autenticación, autorización y fallos del servidor. Usa statusCode para respuestas concretas y .fail() para el caso general.

$.ajax({
  url: "/api/profile",
  method: "PUT",
  contentType: "application/json",
  data: JSON.stringify(profile),
  statusCode: {
    401: function () { window.location.href = "/login"; },
    422: function (jqXHR) { showValidationErrors(jqXHR.responseJSON); }
  }
}).fail(function (jqXHR, textStatus) {
  if (textStatus === "timeout") showMessage("El servidor no respondió a tiempo.");
  else if (jqXHR.status >= 500) showMessage("Error temporal del servidor.");
});

Estados de carga y concurrencia

Desactivar temporalmente el botón evita envíos duplicados. Los eventos globales ajaxStart y ajaxStop pueden controlar un indicador general, pero beforeSend y .always() suelen ser más claros para cada componente.

const $button = $("#save");
$.ajax({
  url: "/api/settings",
  method: "POST",
  data: $("#settings").serialize(),
  beforeSend: function () { $button.prop("disabled", true); }
}).always(function () { $button.prop("disabled", false); });

En búsquedas instantáneas, cancela la petición anterior o ignora respuestas obsoletas; de lo contrario, una respuesta lenta puede sobrescribir resultados recientes.

CORS, credenciales y seguridad

Las peticiones entre orígenes están gobernadas por CORS. El servidor debe enviar cabeceras adecuadas; JavaScript no puede resolver por sí solo una política CORS. Si el servidor admite cookies cross-origin, usa xhrFields: { withCredentials: true }, con un origen explícito y credenciales permitidas en el servidor.

AJAX no sustituye la seguridad del servidor. Valida entradas y permisos, aplica protección CSRF cuando corresponda y no insertes HTML no confiable mediante .html(). Para texto del usuario usa .text(). JSONP ejecuta scripts y es una técnica heredada que no debe usarse con fuentes no fiables.

Cuándo usar jQuery AJAX hoy

En un proyecto nuevo sin dependencias, fetch() suele ser más ligero. En una aplicación que ya usa jQuery, AJAX ofrece una API coherente e integrada con formularios. No añadas jQuery solo para AJAX; aprovéchalo con criterio cuando ya forma parte del stack.

Lista final

• Usar la compilación completa, no slim.
• Definir método, formato, tiempo de espera y errores.
• Distinguir contentType de dataType.
• Usar .done(), .fail() y .always().
• Gestionar duplicados y respuestas fuera de orden.
• Aplicar autenticación, autorización, CSRF y validación en el servidor.
• Mostrar estado de carga y mensajes comprensibles.