Backbone: Combining The where() and toJSON() Collection Methods

The two Backbone collection methods I use most often are probably where(), and toJSON(). However, they're difficult to use together sometimes. For example, I can filter my collection before I actually do anything with it using where(), but this gives me back an array of models. I can't do further Lodash processing on this array, because it has full-fledged models, not objects in it. I can't pass this array to my template context because, again, it's looking for plain objects, and not Backbone model instances.

Less Is More

When it comes to representations returned from a RESTful API, is there a preferred format? If JSON better than XML? More often than not, JSON is the preferred representation format because Ajax web applications are usually making the API requests. And when it is some other application making the request, it is usually trivial to make use of the returned data.

What about returning HTML as a RESTful representation? Isn't it as useful as JSON or XML? I would like to think so, just as long as it is consistent and simple. For instance, returning HTML lists is probably just as easy for clients to parse as retuning some other format. The added benefit is that HTML can be inserted directly into a browser. It can also be styled any any way imaginable.

Using HTML is less because it involves less work on the client end in most cases. It is more because it offers more flexibility.

Django Ajax Response

The Django Python web application framework is capable of many types of data serialization.  Be it, XML, or JSON, The built-in Django serialize() function can handle it.  The transformation typically starts with a Python dictionary or list but can also handle instances of user-defined types.  The end result is always a string.  The string is of course desired because that is what will be passed along inside the HTTP response.  It is nice to have this functionality, but what is it used for?  Why not just use standard templates with template variables and let the view render it for the client?  The main reason is that more and more non-browser clients are being used with web applications.  Even if the client is a web browser, there is a good chance that the request is coming from an ajax application and they don't always like HTML responses.  Most prefer the JSON format.

There is, however, a good chance that more than one format is going to be necessary for the same data set.  For instance, I might have a standard Python dictionary that I want to return to the client.  Depending on who the client is, that same data is going to be rendered differently.  This is so that the client can understand the response.  Say, for instance, that the client was a javascript application.  This client could, potentially, have the ability to selectively handle different response formats that server returns to it.  This responsibility shouldn't really be left to the client application.  It would be nice if the Django application could automatically determine if a javascript application is requesting the data instead of a standard web request.  Thankfully, Django can do this without much developer intervention.

Django HTTP request instances can determine if the request came from an ajax application.  Django does this under the hood by examining the HTTP headers.  As is illustrated by the following example, simple scenarios like this one can be implemented with a single controller.

#Example; Django Ajax response.

#Import Django components.
from django.http import HttpResponse
from django.template import Context, Template
from django.core.serializers import serialize

#Initialize the test data object.
data_obj={"first_name":"First Name", "last_name":"Last Name"}

#The test view.
def index(request):
    #Check if this is an ajax request.
    if request.is_ajax():

        #Set the result to serialized JSON data.
        result=serialize("json", data_obj)

    else:
        #Create a context object from the test data.
        context_obj=Context(data_obj)
        
        #Create a test template string.
        template_str="""<b>first_name</b>: {{first_name}}<br/>
                        <b>last_name</b>:  {{last_name}}"""
                        
        #Set the result to the rendered HTML.
        result=Template(template_str).render(context_obj)

    #Return the response.
    return HttpResponse(result)

An argument against XML

My argument against using XML as a data format in certain situations is that it is too verbose. In other situations, however, the verbosity provided by XML is needed. Such as for human consumption. This is why XML exists, it is easy to use and read by both humans and computers.

The verbosity problem with XML stems from the use of tags. Every entity represented in XML needs needs to be enclosed in a tag. The opening tag indicating that a new entity definition has started and the ending tag indicating the end of that definition. For example, consider the following XML.

<person>
<name>adam</name>
</person>

This is a trivial example of a person entity with a single name attribute. Notice the duplication of the text "person" and "name" in the metadata. With XML this is required. However, tags may also have attributes. Our person definition could be expressed as follows.

<person name="adam"/>

Here there is no metadata duplication. But I think the second example negates the readability philosophy behind XML. What exactly is the difference between attributes and child entities in XML? Semantically, there is none. A child entity is still an attribute of the parent entity.

With JSON, there is no duplication of metadata or any confusion of how an entity is defined. This is because the JSON format is focused on lightweight data, not readability. For instance, here is our person in JSON.

{person:{name:"adam"}}

Now, if a person were reading this, the chances of them getting the meaning right are greatly reduced when compared to the XML equivalent. However, it is much less verbose in most cases. And verbosity counts when data is being transferred over a network. Another plus, the XML is not lost. JSON can easily be converted to XML and back. So if JSON-formatted data must be edited by humans as XML, this is not difficult to achieve.

Here is a simple Python demonstration of reducing the size of XML data with JSON.

#Example; XML string and JSON string

xml_string="""
<entry><title>mytitle</title><body>mybody</body></entry>
"""

json_string="""
{entry:{title:"mytitle",body:"mybody"}}
"""
if __name__=="__main__":
print 'XML Length:',len(xml_string)
print 'JSON Length:',len(json_string)
pcent=float(len(json_string))/len(xml_string)*100
print 'XML size as JSON:',pcent,'%'
   

Finally, since XML is based on tags, there is no opportunity for sets of primitive types. For example, some client says to the server "give me a list of names and nothing else". The client will likely name something along the lines of the following.

<list>
<item name="name1"/>
<item name="name2"/>
<item name="name3"/>
</list>

Here is the JSON alternative.

["name1", "name2", "name3"]

JSON or XML?

Which is the better format for data representation? JSON? or XML? That is a tough one because there are several dimensions here that constitute better. Some easy differences:

• XML is easier to understand, and therefore better for humans to read.
• JSON is more lightweight, and therefor better for software to read.

So how do you go about deciding which format to go with in the context of your application? If the data is constantly manipulated by humans, the answer is easy; XML. In this scenario, the lightweight of JSON simply doesn't pay off. If the data is seldom interpreted by humans but the data format is transferred across a network (which it most likely will), JSON would be the way to go.

Can the two data formats exist within the same context? Yes. Would it make sense to use both formats in the same application? Not likely. One exception I can think of is when using third-party libraries or tools that require one format or the other but you have already invested heavily in the other format. The two formats are isomorphic enough that there is no magic needed to convert between the two. It is just unnecessary if it can be avoided.

If I were to start developing an application from scratch today, and the choice between the two formats needed to be made, I would most likely choose JSON. There are few reasons to not use it. There exist JSON libraries for all the major programming languages. The only question is human interpretation. It would be pretty easy to build a JSON, tree-style, viewer/editor (I've never seen anything out there that does this, and only this). This JSON editor/viewer will be a topic of further discussion in later posts.