[dojo-contributors] dojo/request API change

Bryan Forbes bryan at reigndropsfall.net
Tue Jun 12 13:37:51 EDT 2012


I made this change a few weeks ago, but I wanted to outline it here:

dojo/request now returns a promise that resolves to the content-handled
data. The promise has an extra property on it (response) which resolves
to the frozen (where available) response object for the request:

=====
var promise = request(url, { handleAs: "json" });

promise.then(function(data){
    // data is the response converted from
    // JSON to an Object
});

promise.response.then(function(response){
    // response is an object detailing information
    // about the response
});
=====

This resolves (no pun intended) a problem I encountered when thinking
about how stores would use the return value of a request. Currently, the
following is similar to what is done (this is not meant to be exact):

=====
query: function(query, options){
    return xhr("GET", {
        url: this.target,
        handleAs: "json",
        content: query
    });
}
var def = store.query({}).then(function(items){
    def.ioArgs.xhr.getResponseHeader("Content-Type");
});
=====

To get information about the response (status, headers, etc.), you would
need to access the `ioArgs` property of the returned deferred, but the
deferred would still resolve to the data of the query. Using the old
dojo/request API, we would lose the response information:

=====
query: function(query, options){
    return request(this.target, {
        handleAs: "json",
        query: query
    }).then(function(response){
        return response.data;
    });
}
var promise = store.query({}).then(function(items){
    // no way to get headers
});
=====

Changing to resolving to the handled data with a response information
promise gives us the flexibility of the old API with the benefit of
using promises instead of deferreds:

=====
query: function(query, options){
    return request(this.target, {
        handleAs: "json",
        query: query
    });
}
store.query({}).response.then(function(response){
    var items = response.data;

    response.xhr.getResponseHeader("Content-Type");
});
=====

The response object has also had an API addition: getHeader(headerName).
This function can be used to get headers from the response. If a
provider does not have header information (script and iframe), the
function will return null for any `headerName` passed. The reason I
added this function to the response object is that when I was writing
the node provider, I noticed that headers are accessed differently than
with XHR. With the `getHeaders` function, users can now access headers
in a platform independent way which is consistent with the rest of the
dojo/request API. The following would work in the browser as well as node:

=====
request(url).response.then(function(response){
    var contentType = response.getHeader("Content-Type");
});
=====

-- 
Bryan Forbes
http://www.reigndropsfall.net

GPG Fingerprint
3D7D B728 713A BB7B B8B1  5B61 3888 17E0 70CA 0F3D

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: OpenPGP digital signature
Url : http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20120612/9e16bb57/attachment.sig 


More information about the dojo-contributors mailing list