Creating JavaScript API for first time; request review

Question

I am creating a commercial API for the first time for responsive webpages/web applications (mobile devices).

I am new and, sadly, working alone as well as new to Javascript (long complicated story).

I was just wondering if someone from the industry could offer their professional opinion on the following format of a "get" call:

var getSample = function(params) {
//Returns Object
return $.ajax({ 
    url: URL + 'downloadQuadrat.php',
    type: 'GET',
    data: { 'projectID': params.pid, 'quadratID': params.qid },
    dataType: dataType
});
}

Function call:

var printList = function(lid,options,get) {
var list = $("ul#"+lid);
var promise = get(options);

promise.promise().then(
    function(response) {
        var items = response;
        list.empty();

        $.each(items, function(item,details) {
            var ul = $('<ul/>');
            ul.attr('id', lid+'_'+details.ID);
            var li = $('<li/>')
            .text(details.ID)
            .appendTo(list);
            ul.appendTo(list);

        $.each(details,function(key,value) {
                var li = $('<li/>')
                .text(key+': '+value)
                .appendTo(ul);
            });
        });
    }
);
}

Any input or guidance will be hugely appreciated.

Answer 1

From what I understand, you are building an abstraction layer and making your own functions for your API. Here's what you need:

1. A Namespace

   Sounds very C++-ish but yes, you do need namespaces in JS. This prevents you from polluting the global namespace and have a central go-to object for your functions. For example, jQuery uses jQuery and the $ namespaces for a central collection of their functions. Notice $ in $.each(), $ is actually the namespace (a function actually).

2. Module that code

   Another way to prevent code pollution and collision is to wrap your code in a scope, usually called a "closure". This is just a geeky way of calling a function scope that persists because of something returned that still has reference to that scope. Normally, it's called a module (as in a modular piece of code). A simple way of building a module is to use an "immediate function" or a function that immediately executes. A more detailed explanation how it works is explained here

3. Extensibility

   With modular, namespaced code, usually developers forget to open their modules to extensibility. Because module pattern is like putting a cage around their code, developers forget to actually provide a way to make their module extendable.

   You should provide a way (like provide a function) that allows (limited) access to your module and allow it to attach custom functions from the outside. An example is how jQuery allows plugins to be made.

Here's a short way to make a module, and have your custom functions

(function(namespace){

    namespace.get = function(params){
        ...
    }

}(window.myNamespace = window.myNamespace || {}));

myNamespace.get(params);