How to Use jQuery’s $.ajax() for Asynchronous HTTP Requests

Nowadays, developers tend to move away from jQuery and its handy methods for DOM manipulation and Ajax requests that made it hugely popular. Regarding the Ajax requests, the Fetch API, or alternatively, the Axios library, are now more popular tools for performing asynchronous operations. That said, jQuery is still very much alive and powers almost 70,000 websites worldwide. This means that knowing how to use jQuery is still valuable in the day-to-day work of developers, like supporting legacy codebases or maintaining projects that use jQuery as an important dependency.

Ajax is a technology that allows developers to make asynchronous HTTP requests without the need for a full page refresh. To make the process less cumbersome than it would be in pure JavaScript, devs have been using the jQuery library for years. In my article An Introduction to jQuery’s Shorthand Ajax Methods, I discussed some of jQuery’s most-used Ajax shorthand methods: $.get(), $.post(), and $.load(). They are convenient methods for making Ajax requests in a few lines of code.

Sometimes, we need more control over the Ajax calls we want to make. For example, we want to specify what should happen in case an Ajax call fails or we need to perform an Ajax request but its result is only needed if retrieved within a certain amount of time. In such situations, we can rely on another function provided by jQuery, called $.ajax(), that is the topic of this tutorial.

The $.ajax() Function

The jQuery $.ajax() function is used to perform an asynchronous HTTP request. It was added to the library a long time ago, existing since version 1.0. The $.ajax() function is what every function discussed in the previously mentioned article calls behind the scene using a preset configuration. The signatures of this function are shown below:

$.ajax(url[, settings])
$.ajax([settings])

The url parameter is a string containing the URL you want to reach with the Ajax call, while settings is an object literal containing the configuration for the Ajax request.

In its first form, this function performs an Ajax request using the url parameter and the options specified in settings. In the second form, the URL is specified in the settings parameter, or can be omitted, in which case the request is made to the current page.

The list of the options accepted by this function, described in the next section, is very long, so I’ll keep their description short. In case you want to study their meaning in depth, you can refer to the official documentation of $.ajax().

The settings Parameter

There are a lot of different options you can specify to bend $.ajax() to your needs. In the list below you can find their names and their description sorted in alphabetic order:

• accepts: The content type sent in the request header that tells the server what kind of response it will accept in return.
• async: Set this option to false to perform a synchronous request.
• beforeSend: A pre-request callback function that can be used to modify the jqXHR object before it is sent.
• cache: Set this option to false to force requested pages not to be cached by the browser.
• complete: A function to be called when the request finishes (after success and error callbacks are executed).
• contents: An object that determines how the library will parse the response.
• contentType: The content type of the data sent to the server.
• context: An object to use as the context (this) of all Ajax-related callbacks.
• converters: An object containing dataType-to-dataType converters.
• crossDomain: Set this property to true to force a cross-domain request (such as JSONP) on the same domain.
• data: The data to send to the server when performing the Ajax request.
• dataFilter: A function to be used to handle the raw response data of XMLHttpRequest.
• dataType: The type of data expected back from the server.
• error: A function to be called if the request fails.
• global: Whether to trigger global Ajax event handlers for this request.
• headers: An object of additional headers to send to the server.
• ifModified: Set this option to true if you want to force the request to be successful only if the response has changed since the last request.
• isLocal: Set this option to true if you want to force jQuery to recognize the current environment as “local”.
• jsonp: A string to override the callback function name in a JSONP request.
• jsonpCallback: Specifies the callback function name for a JSONP request.
• mimeType: A string that specifies the mime type to override the XHR mime type.
• password: A password to be used with XMLHttpRequest in response to an HTTP access authentication request.
• processData: Set this option to false if you don’t want the data passed in to the data option (if not a string already) to be processed and transformed into a query string.
• scriptAttrs: Defines an object with additional attributes to be used in a “script” or “jsonp” request.
• scriptCharset: Sets the charset attribute on the script tag used in the request but only applies when the “script” transport is used.
• statusCode: An object of numeric HTTP codes and functions to be called when the response has the corresponding code.
• success: A function to be called if the request succeeds.
• timeout: A number that specifies a timeout (in milliseconds) for the request.
• traditional: Set this to true if you wish to use the traditional style of param serialization.
• type: The type of request to make, which can be either “POST” or “GET”.
• url: A string containing the URL to which the request is sent.
• username: A username to be used with XMLHttpRequest in response to an HTTP access authentication request.
• xhr: A callback for creating the XMLHttpRequest object.
• xhrFields: An object to set on the native XHR object.

That’s a pretty long list, isn’t it? Well, as a developer, you probably stopped reading this list at the fifth or sixth element I guess, but that’s fine. The next section will be more exciting, because we’ll put the $.ajax() function and some of these options into action.

Continue reading How to Use jQuery’s $.ajax() for Asynchronous HTTP Requests on SitePoint.