How to poll an API as part of a $.Deferred()

Question

The below non-functional example should explain what I'm trying to do, I just don't understand the pattern I need to use to accomplish it. I tried googling to understand polling and deferred, but I couldn't find anything I could understand.

I have a function which polls an API, and I want to wait for that polling to return an expected result (waiting for the endpoint to indicate something has changed) before continuing with my main function. What am I doing wrong?

Edit: I should add that what SEEMS to go wrong with the code below is that even though deferred.resolve() eventually gets called, it seems it isn't the same deferred that got returned, so the when never gets activated in main(). I'm guessing it has to do with the timeout, meaning deferred get clobbered on the first repeat. That is my assumption, anyways.

function pollAPI() {
     var deferred = $.Deferred();

     $.ajax({                                                                  
       url: url,                                       
       contentType: 'application/JSON',                                      
       method: 'GET'                                                         
     }).done(function(data){                                                                                                                              
         if (!desiredResult) {                                                 
             setTimeout(function() {                                         
               pollAPI();                            
             }, 1000);                                                       
         } else {                                                            
           deferred.resolve();
         }                                                                                                                                           
     }).error(deferred.reject());                                            

     return deferred.promise();
 }

function main() {
    $.when(pollAPI()).then(function() {
        // do something now that the API has returned the expected result
    });

Answer 1

You can use chaining of subsequent calls to the pollAPI() function to create a single promise that has others chained onto it. That would work like this:

// utility function to create a promise that is resolved after a delay
$.promiseDelay = function(t) {
    return $.Deferred(function(def) {
        setTimeout(def.resolve, t);
    }).promise();
}

function pollAPI() {
    return $.ajax({
        url: url,
        contentType: 'application/JSON',
        method: 'GET'
    }).then(function(data) {
        // some logic here to test if we have desired result
        if (!desiredResult) {
            // chain the next promise onto it after a delay
            return $.promiseDelay(1000).then(pollAPI);
        } else {
            // return resolved value
            return someValue;
        }
    });
}

function main() {
    pollAPI().then(function(result) {
        // got desired result here
    }, function(err) {
        // ended with an error here
    });
}

This has the following benefits:

1. No unnecessary promise is created to try to surround the ajax call that already has a promise. This avoids one of the common promise anti-patterns.
2. Subsequent calls to the API just chain to the original promise.
3. There is no need to use $.when() when you just have a single promise. You can just use .then() directly on it.
4. All errors automatically percolate back to the original promise.
5. This uses the ES6-standard .then() (which actually becomes more legitimately standard in jQuery 3.x - though it works in jQuery 1.x and 2.x with its own non-standard quirks) which makes this logic more compatible with other promise-producing async functions.

Also, a number of other retry ideas here: Promise Retry Design Patterns