This returns a deferred object.

This is the core of building and using promises. The first thing is to get a deferred object, which will have to resolve and reject functions. When the action is successful, call the resolve function; when it fails, call reject. Finally, return the promise with defer.promise.

With the promise, you can call then, which takes two functions. The first will be called when resolve is called, and the second will be called when reject is called. The promise can be passed around and have then called multiple times.

Anytime you are doing anything asynchronous, you should use promises. With Angular, you should use $q as it is tied in with rootscope.

Here is an example where a function will succeed when the number is even and fail when the number is odd. Then, it is executed twice, logging to the console, whether it succeeded or failed. Note that the function is created in the controller, but a utility function like this should be put a service into production:

firstModule.controller('SimpleController', ['$scope', '$q', function ($scope, $q) {
  function qTest(number) {
    console.log($q);
    var defer = $q.defer();

    if (number % 2 === 0) {
      defer.resolve(number);
    } else {
      defer.reject(number);
    }
    return defer.promise;
  };

  qTest(2)
    .then(function (n) { console.log('succeeded!'); }, function (n) { console.log('failed!'); });

  qTest(3)
    .then(function (n) { console.log('succeeded!'); }, function (n) { console.log('failed!'); });

}]);