Ajax with jQuery: $.ajax, get, post and load

An enquiry form sends { name: 'Asha K', services: ['web', 'seo'] } with $.post(), and the PHP script behind it receives name=Asha+K&services%5B%5D=web&services%5B%5D=seo: a form body, not JSON. Change one setting and the same enquiry arrives as JSON text that PHP turns into a single meaningless key, and neither side reports an error.

Every request in this lesson comes from a shop page that ran in jsdom with jQuery 4.0.0, most of them with 3.7.1 as well, and went to a test server that wrote down what it received: each section shows a request as a server sees it. You will read what a call sends, predict the body and Content-Type for objects, JSON, arrays and FormData, handle every way a request can fail, and send a CSRF token without breaking the calls a page makes to other sites.

$.get(), $.post() and .load() are $.ajax() with settings filled in

Every Ajax function of jQuery ends in one call. $.get(url, data, success) is $.ajax() with method: 'GET', $.post() is the same with method: 'POST', and $.getJSON() is a GET with dataType: 'json' (jQuery.get(), jQuery.post(), jQuery.getJSON()). .load(url) is a method of a collection instead: it fetches HTML, with a GET, or a POST when its data is an object, and puts the answer into the selected elements (.load()). Old code reads more easily once each shorthand is written out as the settings it stands for:

The shop’s stock page makes each call once. The test server logged every request, and this run prints the Accept header as well:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Stock and offers</title>
</head>
<body>
  <section id="deals"></section>
  <section id="all"></section>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js" integrity="sha256-OaVG6prZf4v69dPg6PhVattBXkcOWQB62pdZ3ORyrao=" crossorigin="anonymous"></script>
  <script src="shorthands.js"></script>
</body>
</html>

// The shop page's shorthand calls, one after another (each is awaited, so the log stays in order), and what each
// one handed to its callback. The test server logs what each request carried.
const loaded = ($target, url) =>
  new Promise((done) => {
    $target.load(url, (text, textStatus) => {
      console.log(`.load('${url}'): ${textStatus}, the section now holds ${$target.html()}`);
      done();
    });
  });

(async () => {
  await $.get('/srv/stock', { sku: 'K-7310' }, (data, textStatus) => {
    console.log(`$.get: ${textStatus}, data is an ${typeof data}: ${JSON.stringify(data)}`);
  });
  await $.getJSON('/srv/stock', { sku: 'L-0042' }).done((data) => {
    console.log(`$.getJSON: ${data.sku} has ${data.inStock} in stock`);
  });
  await $.post('/srv/echo', { sku: 'K-7310', qty: 2 }, (data) => {
    console.log(`$.post: ${JSON.stringify(data)}`);
  });
  await loaded($('#deals'), '/srv/offers #offers');
  await loaded($('#all'), '/srv/offers');
})();

// Prints what shop/shorthands.js logged in jsdom and what the test server received (recorded.mjs).
import { show } from './show.mjs';

show('shop/shorthands.html', { accept: true });

server: GET /srv/stock?sku=K-7310 from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
  Accept: */*
$.get: success, data is an object: {"sku":"K-7310","inStock":4}
server: GET /srv/stock?sku=L-0042 from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
  Accept: application/json, text/javascript, */*; q=0.01
$.getJSON: L-0042 has 4 in stock
server: POST /srv/echo from XMLHttpRequest, answered 200
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  Accept: */*
  body: sku=K-7310&qty=2
$.post: {"ok":true}
server: GET /srv/offers from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
  Accept: text/html, */*; q=0.01
.load('/srv/offers #offers'): success, the section now holds <div id="offers"><p>Delivery in 2 days</p></div>
server: GET /srv/offers from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
  Accept: text/html, */*; q=0.01
the script in offers ran
.load('/srv/offers'): success, the section now holds <div id="offers"><p>Delivery in 2 days</p></div><p id="other">Not wanted here</p><script>console.log("the script in offers ran")</script>
(jQuery 3.7.1 logged the same 23 lines)

$.get() handed its callback an object, not text: no dataType was given, so jQuery chose one from the answer’s Content-Type, application/json, and parsed the body (jQuery.ajax()). $.getJSON() said what it wanted in its Accept header, and .load() asked for text/html. $.post() sent its object as a form body, sku=K-7310&qty=2, which the next section takes apart. Every request also carried X-Requested-With: XMLHttpRequest, a header that jQuery adds itself and that the last section comes back to.

The two .load() calls fetched the same fragment and treated its script differently. With a selector after the URL, '/srv/offers #offers', jQuery kept only that element and removed the scripts before inserting it. Without one, the whole fragment went in through .html(), and its script ran: the run logged “the script in offers ran” before the callback, as the documentation of .load() describes.

What the server receives depends on data, contentType and processData

The data setting is turned into a request in one of three ways. A plain object goes through $.param(), which writes the bracket names that PHP reads, services[] for each item of a list, and is sent with the default contentType, application/x-www-form-urlencoded; charset=UTF-8 (jQuery.ajax()). A string is sent as it is, still labelled with that default type unless you change contentType; under the form type, jQuery’s one change is to turn each %20 in it into + (src/ajax.js). And with processData: false, jQuery leaves the data alone, which is meant for objects the browser sends itself, such as FormData. Step through one enquiry sent with five settings, and watch what reaches PHP:

The enquiry page makes those five requests, then two GET requests, and the test server logged the Content-Type and the body of each:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Enquiry bodies</title>
</head>
<body>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js" integrity="sha256-OaVG6prZf4v69dPg6PhVattBXkcOWQB62pdZ3ORyrao=" crossorigin="anonymous"></script>
  <script src="bodies.js"></script>
</body>
</html>

// One enquiry sent five ways, then two GET requests. The test server logs the Content-Type and the body of each.
const enquiry = { name: 'Asha K', services: ['web', 'seo'], budget: 50000 };

(async () => {
  // 1. A plain object: jQuery encodes it with $.param() as a form body.
  await $.post('/srv/echo', enquiry);
  // 2. JSON text, while the Content-Type still says it is a form.
  await $.ajax({ url: '/srv/echo', method: 'POST', data: JSON.stringify(enquiry) });
  // 3. JSON text with a JSON Content-Type.
  await $.ajax({ url: '/srv/echo', method: 'POST', contentType: 'application/json', data: JSON.stringify(enquiry) });
  // 4. processData: false with a plain object, so nothing encodes it.
  await $.ajax({ url: '/srv/echo', method: 'POST', processData: false, data: enquiry });
  // 5. A FormData object with a file in it.
  const form = new FormData();
  form.append('name', enquiry.name);
  form.append('brief', new Blob(['Two pages, in Hindi and English'], { type: 'text/plain' }), 'brief.txt');
  await $.ajax({ url: '/srv/echo', method: 'POST', data: form });
  // GET: the data goes into the query string, and cache: false adds a number to the URL.
  await $.get('/srv/echo', { name: enquiry.name, ids: [3, 4] });
  await $.ajax({ url: '/srv/echo', cache: false });
  console.log('sent: 5 bodies, then 2 GET requests');
})();

// Prints what shop/bodies.js logged in jsdom and what the test server received (recorded.mjs).
import { show } from './show.mjs';

show('shop/bodies.html');

server: POST /srv/echo from XMLHttpRequest, answered 200
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  body: name=Asha+K&services%5B%5D=web&services%5B%5D=seo&budget=50000
server: POST /srv/echo from XMLHttpRequest, answered 200
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  body: {"name":"Asha K","services":["web","seo"],"budget":50000}
server: POST /srv/echo from XMLHttpRequest, answered 200
  Content-Type: application/json
  X-Requested-With: XMLHttpRequest
  body: {"name":"Asha K","services":["web","seo"],"budget":50000}
server: POST /srv/echo from XMLHttpRequest, answered 200
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  body: [object Object]
server: POST /srv/echo from XMLHttpRequest, answered 200
  Content-Type: multipart/form-data; boundary=BOUNDARY
  X-Requested-With: XMLHttpRequest
  body: --BOUNDARY
        Content-Disposition: form-data; name="name"
        
        Asha K
        --BOUNDARY
        Content-Disposition: form-data; name="brief"; filename="brief.txt"
        Content-Type: text/plain
        
        Two pages, in Hindi and English
        --BOUNDARY--
        
server: GET /srv/echo?name=Asha%20K&ids%5B%5D=3&ids%5B%5D=4 from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
server: GET /srv/echo?_=<number> from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
sent: 5 bodies, then 2 GET requests

The object became name=Asha+K&services%5B%5D=web&services%5B%5D=seo&budget=50000. The space is a +, because jQuery turns the %20 of $.param() into + in a form body, the form encoding of the URL Standard, a step that moved into $.ajax() in jQuery 3.0 (3.0 upgrade guide). The JSON string of the second request went out unchanged, under the form’s Content-Type, and only the third request labelled it application/json. processData: false with a plain object sent the text [object Object]. The FormData object went as multipart/form-data, with the file in a part of its own; jQuery 4 needs no extra setting for that.

The GET requests put their data in the query string instead, where the space stayed %20, and cache: false added _= and a number that changes with every request, so no cache along the way can answer it.

PHP fills $_POST only from a form body or a multipart body, and parses a form body as parse_str() parses a query string ($_POST, parse_str). A JSON body leaves $_POST empty, and the script reads it from php://input. This program decodes the bodies the server received:

<?php

// decode.php: what PHP makes of three of the bodies that bodies.js sent (bodies.mjs prints them). For a body sent as
// application/x-www-form-urlencoded, PHP fills $_POST as parse_str() parses a query string; a JSON body leaves $_POST
// empty, and the script reads it from php://input with json_decode() instead.

$formBodies = [
    'the object' => 'name=Asha+K&services%5B%5D=web&services%5B%5D=seo&budget=50000',
    'JSON text sent as a form' => '{"name":"Asha K","services":["web","seo"],"budget":50000}',
    'processData: false' => '[object Object]',
];

foreach ($formBodies as $from => $body) {
    parse_str($body, $post);
    echo $from, ': $_POST = ', json_encode($post, JSON_UNESCAPED_SLASHES), "\n";
    echo '  $_POST[\'name\'] is ', isset($post['name']) ? '"' . $post['name'] . '"' : 'not set', "\n";
}

$json = '{"name":"Asha K","services":["web","seo"],"budget":50000}';
$data = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
echo 'JSON with a JSON Content-Type: $_POST = [], json_decode() gives ', json_encode($data, JSON_UNESCAPED_SLASHES), "\n";
echo '  budget is ', get_debug_type($data['budget']), ' here, and ', get_debug_type('50000'), " in a form body\n";

the object: $_POST = {"name":"Asha K","services":["web","seo"],"budget":"50000"}
  $_POST['name'] is "Asha K"
JSON text sent as a form: $_POST = {"{\"name\":\"Asha_K\",\"services\":":{"\"web\",\"seo\"":""}}
  $_POST['name'] is not set
processData: false: $_POST = []
  $_POST['name'] is not set
JSON with a JSON Content-Type: $_POST = [], json_decode() gives {"name":"Asha K","services":["web","seo"],"budget":50000}
  budget is int here, and string in a form body

The form body gave PHP all three fields, the budget as the string "50000", since a form body holds only text. The JSON text sent as a form gave it one odd key, the JSON up to its first [ with the space turned into _, so $_POST['name'] was not set, and [object Object] gave it nothing. None of these requests failed: the server answered 200 to every one.

Every status outside 200–299, a bad JSON body and a timeout end in fail()

A request succeeds when its status is from 200 to 299, or 304, and its body converts to the dataType it asked for (src/ajax.js); anything else calls the fail() callbacks with three values: the jqXHR, a textStatus and an errorThrown (jQuery.ajax()). The jqXHRjqXHR: The object that $.ajax() and its shorthands return: a promise of the request's result that also holds the status, the response text and the headers, with abort() to cancel the request. is the object $.ajax() returns, a promise of the result that also holds the status and the response text. Follow each of the page’s requests down the column:

The error page makes those requests one after another. Its fail() callbacks log the three values, and a handler on document logs every failure a second time:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>When a request goes wrong</title>
</head>
<body>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js" integrity="sha256-OaVG6prZf4v69dPg6PhVattBXkcOWQB62pdZ3ORyrao=" crossorigin="anonymous"></script>
  <script src="errors.js"></script>
</body>
</html>

// Requests that do not succeed, each with a fail() callback that logs the three values jQuery passes it, and a
// handler on document that sees every failure of a request whose global setting is left at true.
$(document).on('ajaxError', (event, jqXHR, settings) => {
  console.log(`  ajaxError on document: ${settings.url}, status ${jqXHR.status}`);
});
const report = (label) => (jqXHR, textStatus, errorThrown) => {
  console.log(`${label}: status ${jqXHR.status}, textStatus "${textStatus}", errorThrown "${errorThrown}"`);
};
// Waits until a request has finished, whatever the outcome, so that the lines stay in order. done() gets no argument:
// a promise resolved with the jqXHR itself would take on the request's failure.
const finished = (jqXHR) => new Promise((done) => jqXHR.always(() => done()));

(async () => {
  await finished($.ajax('/srv/missing').fail(report('404')));
  await finished($.ajax('/srv/broken').fail(report('500')));
  await finished($.ajax({ url: '/srv/empty', dataType: 'json' }).fail(report('empty body as JSON')));
  await finished($.ajax({ url: '/srv/slow', timeout: 100 }).fail(report('timeout of 100 ms')));
  await finished($.ajax({ url: '/srv/missing', global: false }).fail(report('404 with global: false')));
  const pending = $.ajax('/srv/slow').fail(report('abort() after 50 ms'));
  setTimeout(() => pending.abort(), 50);
  await finished(pending);
  await finished(
    $.ajax({ url: '/srv/subscribe', method: 'POST', dataType: 'json' }).done((data, textStatus, jqXHR) => {
      console.log(`204: done() ran, status ${jqXHR.status}, textStatus "${textStatus}", data ${data}`);
    }),
  );
})();

// Prints what shop/errors.js logged in jsdom and what the test server received (recorded.mjs).
import { show } from './show.mjs';

show('shop/errors.html');

server: GET /srv/missing from XMLHttpRequest, answered 404
  X-Requested-With: XMLHttpRequest
404: status 404, textStatus "error", errorThrown "Not Found"
  ajaxError on document: /srv/missing, status 404
server: GET /srv/broken from XMLHttpRequest, answered 500
  X-Requested-With: XMLHttpRequest
500: status 500, textStatus "error", errorThrown "Internal Server Error"
  ajaxError on document: /srv/broken, status 500
server: GET /srv/empty from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
empty body as JSON: status 200, textStatus "parsererror", errorThrown "SyntaxError: Unexpected end of JSON input"
  ajaxError on document: /srv/empty, status 200
server: GET /srv/slow from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
timeout of 100 ms: status 0, textStatus "timeout", errorThrown "timeout"
  ajaxError on document: /srv/slow, status 0
server: GET /srv/missing from XMLHttpRequest, answered 404
  X-Requested-With: XMLHttpRequest
404 with global: false: status 404, textStatus "error", errorThrown "Not Found"
server: GET /srv/slow from XMLHttpRequest, answered 200
  X-Requested-With: XMLHttpRequest
abort() after 50 ms: status 0, textStatus "abort", errorThrown "abort"
  ajaxError on document: /srv/slow, status 0
server: POST /srv/subscribe from XMLHttpRequest, answered 204
  X-Requested-With: XMLHttpRequest
204: done() ran, status 204, textStatus "nocontent", data undefined
(jQuery 3.7.1 logged the same 26 lines)

Two of those rows surprise people. A 200 can fail: the documentation says an empty answer is rejected for JSON, and the server should send null or {} instead. And a 204 succeeds with data undefined, because there is no body to parse. For a parse error, errorThrown is the SyntaxError that JSON.parse() threw, and for an HTTP error it is the status text, which an answer over HTTP/2 does not carry, so there it is an empty string (jQuery.ajax()). Branch on textStatus and the status, never on errorThrown.

The handler on document saw every failure except the one sent with global: false. Global events such as ajaxError, ajaxStart and ajaxStop are attached with .on(): the shorthand methods .ajaxError() and .ajaxStart() were deprecated in jQuery 3.5 (.ajaxStart()), and .on() is what the ajaxError event page shows. A global handler suits logging; the message a form shows belongs in the request’s own fail(), next to the form.

A CSRF token belongs in a header, sent to your own origin only

A CSRF tokenCSRF token: A secret value that a server puts in its own pages and checks on every request that changes data. A request forged by another site cannot know it, so the server refuses that request. proves that a request comes from the site’s own page: the server puts a secret value in the page and refuses any request that changes data without it. OWASP’s cheat sheet recommends sending it from JavaScript in a custom request header, which the server then checks (CSRF Prevention Cheat Sheet). Laravel’s documentation puts the token in a meta tag and adds it to every jQuery request with $.ajaxSetup({ headers: { 'X-CSRF-TOKEN': … } }), and its middleware checks that header (Laravel CSRF protection). That one line has a cost. Step through the enquiry and the exchange rates of the shop page, first with $.ajaxSetup(), then with a prefilter:

The two pages make the same calls; the second adds the token only to requests for its own originorigin: The scheme, host and port of an address, such as https://shop.example. A request to any other origin is cross-origin, and the browser applies the CORS rules to it.:

// The enquiry first goes without the CSRF token, then with the token added by $.ajaxSetup(), the way Laravel's
// documentation shows. The page also loads exchange rates from another origin, api.example.in.
const send = () => $.post('/srv/enquiry', { name: 'Asha K' });
const rates = () => $.getJSON('https://api.example.in/rates');
const outcome = async (label, request) => {
  try {
    console.log(`${label}: ${JSON.stringify(await request())}`);
  } catch (jqXHR) {
    console.log(`${label} failed: status ${jqXHR.status}`);
  }
};

(async () => {
  await outcome('enquiry without the token', send);
  const token = $('meta[name="csrf-token"]').attr('content');
  $.ajaxSetup({ headers: { 'X-CSRF-TOKEN': token } });
  await outcome('enquiry with the token', send);
  await outcome('rates', rates);
})();

// The same calls, with the token added by a prefilter only to requests for the shop's own origin.
const token = $('meta[name="csrf-token"]').attr('content');
$.ajaxPrefilter((options, originalOptions, jqXHR) => {
  if (!options.crossDomain) jqXHR.setRequestHeader('X-CSRF-TOKEN', token);
});
const outcome = async (label, request) => {
  try {
    console.log(`${label}: ${JSON.stringify(await request())}`);
  } catch (jqXHR) {
    console.log(`${label} failed: status ${jqXHR.status}`);
  }
};

(async () => {
  await outcome('enquiry', () => $.post('/srv/enquiry', { name: 'Asha K' }));
  await outcome('rates', () => $.getJSON('https://api.example.in/rates'));
})();

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="csrf-token" content="tok-5d1c">
  <title>Enquiry with a CSRF token</title>
</head>
<body>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js" integrity="sha256-OaVG6prZf4v69dPg6PhVattBXkcOWQB62pdZ3ORyrao=" crossorigin="anonymous"></script>
  <script src="token-setup.js"></script>
</body>
</html>

// Prints what shop/token-setup.js logged in jsdom and what the test server received (recorded.mjs).
import { show } from './show.mjs';

show('shop/token-setup.html');

server: POST /srv/enquiry from XMLHttpRequest, answered 419
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  body: name=Asha+K
enquiry without the token failed: status 419
server: POST /srv/enquiry from XMLHttpRequest, answered 201
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  X-CSRF-TOKEN: tok-5d1c
  body: name=Asha+K
enquiry with the token: {"saved":true}
server: OPTIONS https://api.example.in/rates from XMLHttpRequest, answered 204
  Origin: https://shop.example
  Access-Control-Request-Method: GET
  Access-Control-Request-Headers: X-CSRF-TOKEN
rates failed: status 0
(jQuery 3.7.1 logged the same 16 lines)

// Prints what shop/token-prefilter.js logged in jsdom and what the test server received (recorded.mjs).
import { show } from './show.mjs';

show('shop/token-prefilter.html');

server: POST /srv/enquiry from XMLHttpRequest, answered 201
  Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  X-Requested-With: XMLHttpRequest
  X-CSRF-TOKEN: tok-5d1c
  body: name=Asha+K
enquiry: {"saved":true}
server: GET https://api.example.in/rates from XMLHttpRequest, answered 200
  Origin: https://shop.example
rates: {"INR":1,"USD":0.0113}
(jQuery 3.7.1 logged the same 9 lines)

The test server checks the token on every enquiry, as Laravel 12’s ValidateCsrfToken middleware does (Laravel 12 CSRF protection), and answered 419 Page Expired, Laravel’s status for a token that does not match, until the token came with the request. With $.ajaxSetup(), the token header was also set on the call to api.example.in. A custom header turns a cross-origin request into one the browser must ask about first: an OPTIONS request, the preflightpreflight request: An OPTIONS request that a browser sends before a cross-origin request with a custom header or another method than GET, HEAD or POST, asking the server whether it allows it; the real request goes only if the answer allows it., listed X-CSRF-TOKEN in Access-Control-Request-Headers (Fetch Standard). The API allowed only X-Requested-With, so the GET was never sent and the rates failed with status 0. An API that allowed any header would have received the shop’s token instead, which is why OWASP’s cheat sheet warns against attaching the token to every cross-origin destination. The jQuery documentation advises against $.ajaxSetup() for another reason: its settings reach every later call, plugins included (jQuery.ajaxSetup()).

The prefilter runs before each request, after jQuery has worked out options.crossDomain, and adds the header only when it is false (jQuery.ajaxPrefilter()). The enquiry kept its token, and the rates went as a plain GET with only an Origin header.

X-Requested-WithX-Requested-With: A request header, X-Requested-With: XMLHttpRequest, that jQuery adds to its same-origin Ajax requests. Laravel, Symfony and Rails read it to tell an Ajax call from a page load; fetch() never sends it. follows the same rule inside jQuery: the XHR transport adds it to same-origin requests only, because “conditions for a preflight are akin to a jigsaw puzzle”, as the comment in its source puts it (src/ajax/xhr.js). Servers still read it. Laravel’s request()->ajax() calls Symfony’s isXmlHttpRequest(), which compares the header with XMLHttpRequest (Laravel, Symfony), and Rails’ request.xhr? reads it too (ActionDispatch::Request). Code that replaces $.ajax() has to keep sending it where such a check decides what the server returns.

Practise: fix the enquiry request

The enquiry form has two bugs left from this lesson: its settings send JSON labelled as a form without the token, and its fail() callback shows a message only for a 404. Each step has starting code, a first hint and sample tests; the tests read plain objects shaped like the settings and the jqXHR, so they run without jQuery:

/**
 * The $.ajax() settings that send an enquiry to the shop's PHP endpoint, which reads JSON and checks the CSRF token.
 * @param {{ name: string, services: string[], budget: number }} enquiry @param {string} token
 */
export function enquirySettings(enquiry, token) {
  return {
    url: '/srv/enquiry',
    method: 'POST',
    data: JSON.stringify(enquiry),
    dataType: 'json',
  };
}

import { test, assert } from 'mysmartcopilot:test';
import { enquirySettings } from './enquiry.mjs';

const enquiry = { name: 'Asha K', services: ['web', 'seo'], budget: 50000 };

test('posts to /srv/enquiry and asks for a JSON answer', () => {
  const s = enquirySettings(enquiry, 'tok-5d1c');
  assert.equal(s.url, '/srv/enquiry');
  assert.equal(String(s.method ?? s.type).toUpperCase(), 'POST');
  assert.equal(s.dataType, 'json');
});

test('sends the enquiry as JSON text with the JSON Content-Type', () => {
  const s = enquirySettings(enquiry, 'tok-5d1c');
  assert.equal(s.contentType, 'application/json');
  assert.equal(typeof s.data, 'string');
  assert.deepEqual(JSON.parse(s.data), enquiry);
});

test('carries the token in X-CSRF-TOKEN and in no other header', () => {
  assert.deepEqual(enquirySettings(enquiry, 'tok-5d1c').headers, { 'X-CSRF-TOKEN': 'tok-5d1c' });
  assert.deepEqual(enquirySettings(enquiry, 'tok-9a0e').headers, { 'X-CSRF-TOKEN': 'tok-9a0e' });
});

test('leaves the enquiry it is given unchanged', () => {
  const before = JSON.stringify(enquiry);
  enquirySettings(enquiry, 'tok-5d1c');
  assert.equal(JSON.stringify(enquiry), before);
});

/**
 * The text the enquiry form shows when a request fails, from the jqXHR and the textStatus that fail() receives.
 * @param {{ status: number, responseJSON?: { errors?: Record<string, string[]> } }} jqXHR @param {string} textStatus
 * @returns {string}
 */
export function failMessage(jqXHR, textStatus) {
  if (jqXHR.status === 404) return 'Not found.';
}

import { test, assert } from 'mysmartcopilot:test';
import { failMessage } from './message.mjs';

test('says nothing for a request the page cancelled itself', () => {
  assert.equal(failMessage({ status: 0 }, 'abort'), '');
});

test('tells a timeout from a lost connection, though both have status 0', () => {
  assert.equal(failMessage({ status: 0 }, 'timeout'), 'The server took too long to answer. Please try again.');
  assert.equal(failMessage({ status: 0 }, 'error'), 'No connection to the server. Check your network and try again.');
});

test('reports an answer that is not JSON, though its status is 200', () => {
  assert.equal(failMessage({ status: 200 }, 'parsererror'), 'The server sent an answer the page cannot read.');
});

test('asks for a reload when the CSRF token has expired', () => {
  assert.equal(failMessage({ status: 419 }, 'error'), 'Your session has expired. Reload the page and send the form again.');
});

test('shows the first validation message of a 422, or a general one', () => {
  const invalid = { status: 422, responseJSON: { message: 'Invalid.', errors: { email: ['The email field must be a valid email address.'], name: ['Too short.'] } } };
  assert.equal(failMessage(invalid, 'error'), 'The email field must be a valid email address.');
  assert.equal(failMessage({ status: 422 }, 'error'), 'Please check the form and send it again.');
  assert.equal(failMessage({ status: 422, responseJSON: { errors: {} } }, 'error'), 'Please check the form and send it again.');
});

test('names the status of any other failure', () => {
  assert.equal(failMessage({ status: 500 }, 'error'), 'Something went wrong (status 500). Please try again.');
  assert.equal(failMessage({ status: 404 }, 'error'), 'Something went wrong (status 404). Please try again.');
});

Then work through the lesson’s questions. They come one by one, starting from the idea you know least, and each answer you pick explains itself:

Interview questions

Warm-up, for freshers and 2–5 years: how do $.get(), $.post() and $.ajax() differ?

$.ajax() is the one function that sends every request; $.get() and $.post() call it with the method filled in and take the URL, the data, a success callback and a dataType as arguments. They return the same jqXHR, so .done(), .fail() and await work on all three. Use $.ajax() when a call needs a setting the shorthands cannot pass, such as contentType, headers, timeout or processData; use the shorthands for plain GETs and form posts. $.getJSON() is a GET that asks for JSON, and .load() puts the HTML it fetches into the page.

Two harder questions from this module’s bank start from this lesson: an endpoint whose $_POST arrives empty, and a CSRF header that broke a call to another site. Try each one before you read its first step:

Key takeaways

• $.get(), $.post(), $.getJSON() and .load() all call $.ajax() with settings filled in, and .load() without a selector runs the scripts of the HTML it inserts.
• An object is sent as a form body with brackets and + for spaces, a string is sent as it is under the default form Content-Type, and JSON needs contentType: 'application/json', or PHP’s $_POST gets nothing it can use.
• fail() runs for every status outside 200–299 and 304, for a body that does not parse, for a timeout and for an abort; a 204 succeeds with no data.
• Read textStatus before the status: timeouts, aborts and lost connections all have status 0.
• Send a CSRF token only to your own origin, from a prefilter or the call’s settings: with $.ajaxSetup() it reaches other origins, and its custom header forces a preflight there.