Building an API Wrapper in Phone Gap

Yesterday I worked on a PhoneGap Build API wrapper for Node. This already exists -https://github.com/germallon/phonegapbuildapi - but I thought it would be a fun experiment. The Build API is real simple so I assumed my code would also be pretty simple. It was... at first.

I began by working on the Read portions of the API. This allows for things like getting apps, icons, downloads, etc. PhoneGap allows you to request a token or pass the authentication information in every hit. I took the easy way out and simply passed the auth with each request. I was able to wrap up most of the logic for all of the API calls with two utility functions:

function getConfig(path) {
    return {
        auth: username + ":" + password,
        host:"build.phonegap.com",
        port:"443",
        path:"/api/v1/"+path
    }
}

//I handle doing the config get, http, string contact, etc
function doCall(path, success, fail) {
    var options = getConfig(path);
    var req = http.get(options, function(res) {
        var resultString = "";
        res.on("data", function(c) {
            resultString+=c;
        });
    
        res.on("end",function() {
            var result = JSON.parse(resultString);
            success(result);
        });
    }).on("error", function(e) {
        if(fail) fail(e);
    }); 

The core function here is doCall, which expects a path to the API. All the API calls share the same base URL, so I made it simpler by just passing the additional part needed. HTTP calls in Node are a bit more complex than CF because they are asynchronous, but not difficult. You can probably guess what is going on here. I open a request which gets a result object. The result object has a data event which means crap streamed in. I append it to a variable. There is an end event which fires - you guessed it - at the end. I can then just parse the result and fire off a success handler.

So as an example, here is the API to get all apps: 

    doCall("apps", function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res.apps);
    },function(e) {
        if(fail) fail(e);
    });

 And finally, here is how a Node app could make use of it:

pgbuild = require("./pgbuild");

pgbuild.setUsername("ray@camdenfamily.com");
pgbuild.setPassword("isitmillertimeyet?");

//Test getting all the apps
pgbuild.getAllApps(function(apps) {
    console.log("I got lots of apps! How many? "+apps.length);
    //console.dir(apps);
}, function(e) {
    console.log("Oh snap, an error");
    console.dir(e);

 Most of the code I wrote for the read API follows this format - ask for crap and pass a success/fail handler.

So - as I said - this was all pretty simple. I think I burned through the Read API in about 30 minutes or so. It was Unicorns and Rainbows fun all around. Then I began to work on the Write API and hit a brick wall. Why? The Write API, or rather the part I was working on - creating apps - allows you to upload files when defining the new application. You can also point new apps at a repository but I wanted to work on the file version first. (Call me a glutton for punishment - I knew it would be trouble.) Turns out that uploading files is a major pain in the rear. As in - there is no real built in support in the core Node.js libraries. Googling was really difficult as well since almost every result was about processing a file upload, not making a file upload request.

After even more furious Googling (and a quick Diablo 3 break), I found this post. I'd love to actually name the guy or gal - but his About page doesn't actually say who he or she is. Therefore I've decided this person is...

... just because s/he/it was so damn helpful. I incorporated some of his logic into my final code, and while I'm not terribly happy with the mashup, it is working correctly. Here's an example of the call: 

    create_method:"file",
    file:"./forupload/index.html"
    }, function(res) {
        console.log("Ok in making an app");
        console.dir(res);
    }, function(e) {
        console.log("I got an error: ");
        console.dir(e);
    }
);
view rawgistfile1.js

 And here it is up on the shiny new PhoneGap Build site...

Interestingly - browsers have made file uploads in JavaScript much easier with XHR2. If you haven't seen this in action, check out the excellent HTML5 Rocks article on it.

For folks who want to play with this, I've included the entire pgbuild.js code below. Remember - I've been writing Node.js for about a week - so if you use this in production you have my admiration.

var http = require("https");
var fs = require("fs");
var path = require("path");

var username = "";
var password = "";

exports.setUsername = function(u) { username = u; }
exports.setPassword = function(p) { password = p; }

exports.createApp = function(options, success, fail) {
    var httpOptions = getConfig("apps");
    httpOptions.method = "POST";
    
    //Detect if options.create_method is file, and if so, suck in the bits
    //Fails if no .file
    //Also note it doesn't support .zip yet.
    if(options.create_method === "file") {
        if(!options.file) throw new Error("Must supply file value.");
        console.log("Need to read in a file:"+options.file);
        //Shell out for file uploads
        PreparePost(httpOptions,JSON.stringify(options), options.file, success);
    } else {
        //TODO
    }
    
}

exports.getAllApps = function(success,fail) {
    doCall("apps", function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res.apps);
    },function(e) {
        if(fail) fail(e);
    });
}

exports.getApp = function(id, success, fail) {
    doCall("apps/"+id, function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res);
    },function(e) {
        if(fail) fail(e);
    });
}

exports.getAppIcon = function(id, success, fail) {
    doCall("apps/"+id +"/icon", function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res.location);
    },function(e) {
        if(fail) fail(e);
    });
}

//todo: Possibly validate platform? Should be: android,blackberry,ios,symbian,webos,winphone
exports.getAppDownload = function(id, platform, success, fail) {
    doCall("apps/"+id +"/"+platform, function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res.location);
    },function(e) {
        if(fail) fail(e);
    });
}

exports.getKeys = function() {
    var platform = "";
    if(arguments.length == 1) {
        success = arguments[0];
    } else if(arguments.length === 2) {
        success = arguments[0];
        fail = arguments[1];
    } else if(arguments.length == 3) {
        platform = arguments[0];
        success = arguments[1];
        fail = arguments[2];
    } 
    
    var path = "keys";
    if(platform != "") path+="/"+platform;
    
    doCall(path, function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res.keys);
    },function(e) {
        if(fail) fail(e);
    });
}

exports.getKey = function(platform, id, success, fail) {
    doCall("keys/"+platform +"/"+id, function(res) {
        if(res.error && res.error.length && fail) fail(res.error);
        else success(res);
    },function(e) {
        if(fail) fail(e);
    });
}

function getConfig(path) {
    return {
        auth: username + ":" + password,
        host:"build.phonegap.com",
        port:"443",
        path:"/api/v1/"+path
    }
}

//I handle doing the config get, http, string contact, etc
function doCall(path, success, fail) {
    var options = getConfig(path);
    var req = http.get(options, function(res) {
        var resultString = "";
        res.on("data", function(c) {
            resultString+=c;
        });
    
        res.on("end",function() {
            var result = JSON.parse(resultString);
            success(result);
        });
    }).on("error", function(e) {
        if(fail) fail(e);
    });
}



//CREDIT: http://onteria.wordpress.com/2011/05/30/multipartform-data-uploads-using-node-js-and-http-request/
//Note that I modified his code quite a bit

//For file uploads
function EncodeFieldPart(boundary,name,value) {
    var return_part = "--" + boundary + "\r\n";
    return_part += "Content-Disposition: form-data; name=\"" + name + "\"\r\n\r\n";
    return_part += value + "\r\n";
    return return_part;
}

function EncodeFilePart(boundary,type,name,filename) {
    var return_part = "--" + boundary + "\r\n";
    return_part += "Content-Disposition: form-data; name=\"" + name + "\"; filename=\"" + filename + "\"\r\n";
    return_part += "Content-Type: " + type + "\r\n\r\n";
    return return_part;
}

//I expect the config options, the JSON data string, and file path
function PreparePost(httpOptions,data,file,success) {
    var boundary = Math.random();
    var post_data = [];

    post_data.push(new Buffer(EncodeFieldPart(boundary, 'data', data), 'ascii'));
    post_data.push(new Buffer(EncodeFilePart(boundary, 'text/plain', 'file', path.basename(file)), 'ascii'));

    var contents = fs.readFileSync(file, "ascii");
    post_data.push(new Buffer(contents, "utf8"));
    post_data.push(new Buffer("\r\n--" + boundary + "--"), 'ascii');
    
    MakePost(httpOptions,post_data, boundary,success);
}

function MakePost(httpOptions,post_data, boundary,success) {

    var length = 0;
    
    for(var i = 0; i < post_data.length; i++) {
        length += post_data[i].length;
    }

    httpOptions.headers = {
        'Content-Type' : 'multipart/form-data; boundary=' + boundary,
        'Content-Length' : length
    };

    var post_request = http.request(httpOptions, function(response){
        response.setEncoding('utf8');
        var res="";
        response.on('data', function(chunk){
            res+=chunk;
        });
        response.on('end',function() {
            success(JSON.parse(res));
        });
    });

    for (var i = 0; i < post_data.length; i++) {
        post_request.write(post_data[i]);
    }
    post_request.end();