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

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 previous 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.

Key Takeaways

1. Versatility and Control: The jQuery $.ajax() function offers a flexible and powerful way to make asynchronous HTTP requests, allowing developers extensive control over the request and response process. It supports a wide array of settings, such as specifying callback functions for success and error, setting request headers, and handling data types, which makes it highly adaptable to various scenarios beyond the capabilities of shorthand Ajax methods like $.get(), $.post(), and $.load().

2. Comprehensive Configuration Options: The article highlights the comprehensive list of configuration options available with $.ajax(), which can cater to nearly any requirement one might have while making Ajax calls. From modifying request headers to processing response data, and from handling errors to setting up cross-domain requests, $.ajax() provides developers with the tools necessary to fine-tune their Ajax requests and responses to fit their application’s needs precisely.

3. Relevance in Modern Development: Despite the advent of newer APIs like Fetch, the jQuery $.ajax() function remains a relevant and valuable tool in web development, especially for maintaining legacy codebases or for developers who prefer the simplicity and consistency offered by jQuery. Its ease of use, combined with the depth of functionality, ensures that $.ajax() can still play a crucial role in projects that require Ajax calls, highlighting jQuery’s ongoing utility in the web development ecosystem.

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 $.get(), $.post(), and $.load() 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.

Putting It All Together

In this section, we’ll see this function and some of its options in action.

A First Example of $.ajax()

We’ll start with a simple demo that reproduces the same code we developed in the previous article. As a recap, we will imagine that we have an element in our website having an ID of main that represents the main content. What we want to do is asynchronously load the main content of the pages referenced by the links in the main menu, which ideally has main-menu as its ID. We want to retrieve only the content inside this element because the other parts of the layout don’t change, so they don’t need to be loaded.

This approach is intended as an enhancement, because if the user visiting the website has JavaScript disabled, they will havethe fallback of still being able to browse the website using the usual synchronous mechanism. In this example we’re assuming that all the links in the menu are internal links.

We’ll start with a simple demo that reproduces the same code we developed in the previous article, but this time we’ll adopt $.ajax(). The code we developerd previously is shown below for your convenience:

$('#main-menu a').on('click', function(event) {
  event.preventDefault();

  $('#main').load(this.href + ' #main *', function(responseText, status) {
  if (status === 'success') {
    $('#notification-bar').text('The page has been successfully loaded');
  } else {
      $('#notification-bar').text('An error occurred');
    }
  });
});

Updating this snippet to employ the $.ajax() function, we obtain the code shown below:

$('#main-menu a').on('click', function(event) {
  event.preventDefault();

  $.ajax(this.href, {
    success: function(data) {
      $('#main').html($(data).find('#main *'));
      $('#notification-bar').text('The page has been successfully loaded');
},
    error: function() {
      $('#notification-bar').text('An error occurred');
    }
  });
});

Here you can see that I used the first form of the function. I’ve specified the URL to send the request to as the first parameter and then a settings object as the second parameter. The latter takes advantage of just two of the several properties discussed in the previous section — success and error — to specify what to do in case of success or failure of the request respectively.

Retrieving a Talk from Joind.in Using $.ajax()

The second example I want to discuss creates a JSONP request to retrieve some information from a service called Joind.in. This is a website where event attendees can leave feedback on an event and its sessions. Specifically, I’m going to create a snippet of code that, using the $.ajax() function, retrieves the title and the description of my talk Modern front-end with the eyes of a PHP developer.

The code to achieve this goal is as follows:

$.ajax({
  url: 'http://api.joind.in/v2.1/talks/10889',
  data: {
    format: 'json'
  },
  error: function() {
    $('#info').html('<p>An error has occurred</p>');
  },
  dataType: 'jsonp',
  success: function(data) {
    var $title = $('<h1>').text(data.talks[0].talk_title);
    var $description =  $('<p>').text(data.talks[0].talk_description);
    $('#info')
    .append($title)
    .append($description);
  },
  type: 'GET'
});

In the snippet above, I employed several of the properties listed above. First of all, you can see that I’m using the second form of $.ajax(), which allows me to specify the URL to which the request is sent as a property (url) of the object literal. Because the Joind.in’s API accepts a JSONP request, in the code above I’m setting the type of request I want to use by specifying the dataType property. Then, I used the data property to define the format’s type that I want to obtain from the server as required by the API. However, the latter requires this data as part of the query string of a GET request, hence I’m also specifying the type property setting GET as its value. Finally, I wrote an error callback to display a message in case of error, and a success callback to display the title and the description of the talk in case of success.

A live demo of this code is shown below:

Debugging AJAX Requests

Debugging AJAX requests can sometimes be tricky due to their asynchronous nature and the involvement of both client-side and server-side code. Here are some effective tips for debugging issues related to the jQuery $.ajax() method:

1. Use Browser Developer Tools

• Network Tab: Check the Network tab in your browser’s developer tools to inspect the AJAX request. Verify the request URL, headers, payload, and response. Look for any errors or unexpected status codes.

• Console Tab: Look for JavaScript errors or warnings in the Console tab that might indicate problems with your AJAX call or its callback functions.

2. Check the Server-Side Logs

• If the AJAX call reaches the server but doesn’t behave as expected, check the server-side logs for errors or warnings. This can provide clues about issues in the server-side code or configuration.

3. Log Request and Response

• Temporarily add console.log() statements in the success, error, and complete callbacks of the $.ajax() call to log the response or any error messages. This can help you understand what the server is returning or why the request might be failing.

4. Verify the Data Type

• Ensure that the dataType option in your $.ajax() call matches the actual type of data returned by the server. Mismatches here can cause jQuery to incorrectly process the response, leading to unexpected behavior.

5. Test API Endpoints Separately

• Use tools like Postman or curl to manually test the API endpoint. This can help you verify that the API is working correctly and understand the expected request format and response data.

6. Validate JSON Responses

• If you’re working with JSON data, validate the JSON response using an online validator or tool to ensure it’s well-formed. Malformed JSON can cause parsing errors.

7. Use jQuery.ajaxError() for Global Error Handling

• Bind an event handler to ajaxError on the document to catch and handle AJAX request errors globally. This can help you identify and debug AJAX requests that fail across your application.

$(document).ajaxError(function(event, jqxhr, settings, thrownError) {
    console.error("AJAX Request Failed: ", settings.url, thrownError);
});

8. Check Cross-Origin Resource Sharing (CORS) Policies

• If making requests across domains, ensure that CORS policies on the server support your requests. CORS issues can prevent AJAX requests from successfully completing.

9. Debug Asynchronous Flow

• For complex asynchronous logic, use console.trace() or breakpoints in the browser’s debugger to trace the execution flow and identify where things might be going wrong.

10. Simplify and Isolate

• Simplify your $.ajax() call or isolate it in a simple environment/page to verify its behavior without interference from other scripts or AJAX calls.

Optimizing the Performance of AJAX Requests

Optimizing the performance of AJAX requests is crucial for creating fast and responsive web applications. When using the jQuery $.ajax() function, consider the following tips to enhance performance:

1. Use GET for Retrieving Data

• GET requests are generally faster and can be cached by the browser. Use GET for retrieving data whenever possible, and reserve POST for actions that change the server’s state.

2. Limit Data Transfer

• Minimize Payload Size: Send and receive only the data that is necessary. Large payloads can significantly slow down your application.

• Compress Data: Use compression techniques for both request and response data if your server and clients support it.

3. Cache Responses

• Leverage Browser Cache: For data that doesn’t change frequently, you can set cache headers on the server side to allow the browser to cache the response.

• Implement Application-Level Caching: Cache data within your application when possible to avoid unnecessary network requests.

4. Asynchronous Requests

• Make sure your requests are asynchronous (async: true, which is the default) to prevent blocking the main thread. This keeps your application responsive while the data is being fetched.

5. Batch Requests

• Reduce HTTP Requests: Combine multiple requests into a single one if you’re fetching data from the same endpoint, reducing the overhead of multiple HTTP connections.

6. Use Promise Chains for Multiple Requests

• If you have dependent requests, use jQuery’s promise and .then() chaining to handle them in a clean and efficient way, reducing callback nesting and improving readability.

7. Error Handling

• Implement robust error handling to deal with failed requests. Avoid unnecessary retries for requests that are likely to fail repeatedly.

8. Timeout Configuration

• Set a reasonable timeout for your AJAX requests (timeout setting). This prevents requests from hanging indefinitely and degrading the user experience.

9. Avoid Unnecessary AJAX Calls

• Before making a request, check if the data is already available on the client-side or if the operation is really necessary.

10. Consider Newer Technologies

• Consider using the Fetch API with async/await for a more modern approach to asynchronous HTTP requests, which offers improved performance and cleaner code.

11. Optimize Server-Side Processing

• Ensure that the server-side processing of AJAX requests is optimized. Faster server responses lead to better performance.

12. Minimize DOM Manipulations

• When updating the DOM based on AJAX responses, minimize the number of manipulations and reflows. Use document fragments or batch updates to the DOM.

Conclusion

In this tutorial I discussed the most powerful of the Ajax functions offered by jQuery, $.ajax(). It allows you to perform Ajax requests with a lot of control over how the request is sent to the server and how the response is processed. Thanks to this function, you have the tools you need to satisfy all of your project’s requirements in case none of the shorthand functions is a good fit.

To have an even better understanding of the potential of this function, I encourage you to play with the code samples, and to try to modify the code to use some other options accepted by the settings parameter.

If you want to learn more about JavaScript, check out our JavaScript titles at SitePoint Premium. Have fun!

FAQs about jQuery’s Ajax Function