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

    function(response) {
        var items = response;

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

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

Any input or guidance will be hugely appreciated.

  • \$\begingroup\$ Is getSample supposed to be getting or setting? It seems to do both. \$\endgroup\$ Commented Dec 12, 2012 at 1:22
  • \$\begingroup\$ 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 \$\endgroup\$ Commented Dec 12, 2012 at 1:30
  • \$\begingroup\$ 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). \$\endgroup\$ Commented Dec 12, 2012 at 1:31
  • \$\begingroup\$ I've updated the code, with the new "promise" structure. Is it correct? \$\endgroup\$ Commented Dec 12, 2012 at 2:17
  • 1
    \$\begingroup\$ 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. \$\endgroup\$
    – lucideer
    Commented Dec 12, 2012 at 9:37

1 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


    namespace.get = function(params){

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

  • \$\begingroup\$ 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 \$\endgroup\$ Commented Dec 16, 2012 at 20:42

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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