Making Requests

A "request" to an FX service includes the full request and response lifecycle of a call to an operation on a service object, including any retries that are transparently attempted on your behalf. A request is encapsulated in the SDK by the FX.Request object. The semantics of a request are described below, specifically, the support for callbacks, events, and streaming of raw HTTP response data.

Asynchronous Callbacks

All requests made through the SDK are asynchronous and use a callback interface. Each service method that kicks off a request can accept a callback as the last parameter with the signature function(error, data) { ... }. This callback will be called when the response or error data is available.

For example, the following service method can be called with a standard callback to retrieve the response data or error:

new FX.Project().listProjects(function(error, data) {
  if (error) {
    console.log(error); // an error occurred
  } else {
    console.log(data); // request succeeded
  }
});

The error and data parameters are described in the "Response Object" section below.

Note that if you do not specify a callback, the operation will return an FX.Request object that must be manually sent using the send() method:

// create the FX.Request object
var request = new FX.Project().listProjects();

// register a callback to report on the data
request.on('success', function(resp) {
  console.log(resp.data); // log the successful data response
});

// send the request
request.send();

The Response Object (FX.Response)

The response object is passed into each callback function so that you can access response data. The FX.Response object that is passed in contains two important properties to get at this data.

When using the standard callback mechanism, the two properties will be made available as parameters on the callback method in the form: function(error, data) { ... }

The data property

The response.data property contains the serialized object data retrieved from the service request. For instance, for an FX.Project listProjects method call, the response data might look like this:

> response.data
{
  Projects: [
    {
        ProjectId: ...
        Name: ...
    },

    {
        ProjectId: ...
        Name: ...
    }
  ]
}

The data property can be null if an error occurs (see below).

The error property

In the event of a service error (or transfer error), the response.error property will be filled with the given error data in the form:

{ code: 'SHORT_UNIQUE_ERROR_CODE',
  message: 'Some human readable error message' }

In the case of an error, the data property will be null. Note that if you handle events that can be in a failure state, you should always check whether response.error is set before attempting to access the response.data property.

The request property

Access to the originating request object is available through this property. For example, to access the parameters that were sent with a request:

prj.getAsset({Name: 'aName'}).on('success', function(response) {
  console.log("Name was", response.request.params.Name);
}).send();

Simplified Callback Method

Each operation supports a simplified callback that can be passed as the last parameter to any service operation. The callback function should accept an error parameter, followed by the data from the response.

For example:

prj.listProjects(function(error, data) {
  if (error) {
    console.log(error); // error is Response.error
  } else {
    console.log(data); // data is Response.data
  }
});

The error and data parameters accepted are equivalent to the error and data properties discussed in the FX.Response response object section above.

If you are passing parameters to the operation, the callback should be placed after the parameters:

prj.getAsset({ProjectId: '123456789-abcd-4321-98876fecb', 
              Name: "video.mp4"}, function(error, data) {
  // ...
});

FX.Request Events

You can alternatively register callbacks on events provided by the FX.Request object returned by each service operation method. This request object exposes the success and error events, each taking a callback that accepts the response object.

Note that if you omit the simplified callback parameter on the operation method, you must call send() on the returned request object in order to kick off the request to the remote server.

Event: 'success'

This event triggers when a successful response from the server is returned. The response contains a .data field with the serialized response data from the service.

var req = prj.listProjects()
req.on('success', function(response){
  console.log(response.data);
})
req.send();

Event: 'error'

This event triggers when a successful response from the server is returned. The response contains a .error field with the serialized error data from the service.

var req = prj.listProjects()
req.on('error', function(response){
  console.log(response.error);
})
req.send();

Multiple Callbacks and Chaining

You can register multiple callbacks on any request object. The callbacks can be registered for different events, or all for the same event. In addition, you can chain callback registration, for example:

prj.listProjects()
  .on('error', function(response){
    console.log("Error!");
  })
  .on('success', function(response){
    console.log("Success!");
  })
  .on('complete', function(response){
    console.log("Complete!");
  })
  .send();

The above example will print either "Success! Complete!", or "Error! Complete!", depending on whether the request succeeded or not.

Support for Promises

Each operation supports returning a promise if promises are globally available when the SDK in imported or a Promises implementation is provided to the SDK.

Setting a Promise Dependency

By default, the SDK will add the promise() method to FX.Request if the Promise constructor is available globally, either natively or pulled in by a 3rd party library. It is also possible to configure the SDK to use a 3rd party implementation of promises, such as bluebird, instead:

// Bluebird already loaded
FX.config.promisesDependency = Promise;

Pass in your favorite Promise library to FX.config.setPromisesDependency or call it without a parameter to revert back to whichever Promise implementation is globally available.

Returned Promise Method

The promise() method is called directly on a FX.Request object. Remember that a request is returned when an operation is called without a callback function supplied. Callbacks can still be registered to events emitted by the request. Calling the promise() method will immediately send then the request, and return a promise that is fulfilled with the response data property or rejected with the response error property:

// create the FX.Request object
var request = new FX.Project().listProjects();

// create the promise object
var promise = request.promise();

// handle promise's fulfilled/rejected states
promise.then(
  function(data) {
    /* process the data */
  },
  function(error) {
    /* handle the error */
  }
);