Take the 2-minute tour ×
Code Review Stack Exchange is a question and answer site for peer programmer code reviews. It's 100% free, no registration required.

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.

share|improve this question
    
Is getSample supposed to be getting or setting? It seems to do both. –  David Dec 12 '12 at 1:22
    
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 –  Griff McGriff Dec 12 '12 at 1:30
    
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). –  David Dec 12 '12 at 1:31
    
I've updated the code, with the new "promise" structure. Is it correct? –  Griff McGriff Dec 12 '12 at 2:17
1  
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. –  lucideer Dec 12 '12 at 9:37
show 1 more comment

1 Answer

up vote 3 down vote accepted

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);
share|improve this answer
    
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 –  Griff McGriff Dec 16 '12 at 20:42
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.