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.

• David Hellsing: Is getSample supposed to be getting or setting? It seems to do both.
• Griff McGriff: getSample is supposed to retrieve a sample from the database, save it as an object, and add it to array. When you call the function, it returns the JSON object, so essentially it's just a "get". A "setSample" will add/update to the database
• David Hellsing: So, getSample is not a part of the API? Is it an example of an implementation? Because you have problems with the function returning a JSON array that doesn’t exist (yet).
• Griff McGriff: I've updated the code, with the new "promise" structure. Is it correct?
• lucideer: Have you tested either of the above code blocks? Do they work as you intended? If not, this seems like more of a question for Stack Overflow ("how do I do this") rather than Code Review ("is this the best way to do this"). I can't figure out what the second code block should do (your get function is undefined and .promise() with no params is used for monitoring animations. With your $.ajax() example, it seems to me you need to at least look at using the .done() chained method for a start.

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);

• Griff McGriff: thank you for that. I am actually from a C background, it's the web side of things (and JS etiquette) I struggle with. I will certainly refer to your comment when structuring my API