View Models and Yet Another Layer

Imagine that we could just transfer the data model our application uses, straight to the client. The client user interface can use this model, the same model the server-side components are using. What's the point? The shared data model, in theory, is a big win because you get at least some level of consistency. The view model is the representation of the application model I'm talking about here - it gets transferred to the client. A replica, as it were, of the reference model. The canonical model that any application components, client or server, should reference.

No Fixed Address

All content out there on the web has a fixed address. But the objects that reside in the implementation of these web resources do not. At least not in a URL-sense. These are objects that live in the database, in cache, or in the web server's memory, as part of an intermediary step toward the finished product that is ultimately delivered to the client. What these objects do have that strikes a similarity with URL-thinking is a unique identifier. These identifiers tell us that this object has it's own state, unique to itself in some context. The context in which these objects are unique is usually constrained to the application. For instance, the primary key that identifies a row in a database table is a common object identifier. The context in which we're assigning identifiers to objects is growing more important, as time moves on, because there is a growing need that the applications we develop integrate seamlessly with one another.

Passing URIs

Uniform Resource Identifiers (URIs) are what enable us to find things on the web. These things refer to a resource, uniformly identified by a string. A resource is any digital media that has been made available on the Internet. At a higher level, search engines are what allow us to find resources that live somewhere in the web. Without a URI, there would be nothing useful for the search engines to display in their results. Additionally, it would be impossible for search engines to crawl websites without theURIs that make up the structure of the site.

APIs can be built with a set of URIs as well. These URI-centric APIs are sometimes referred to as RESTful APIs. RESTful APIs have a close association with the HTTP protocol. Because of this we can pass parameters to resources through GET or POST requests made by a client. But these are often primitive types that can be represented as a string. For instance, if I'm using someAPI to update my user profile, a numeric user ID might be a POST parameter I need to send. This is necessary so the application knows which user to update. But what if I were able to pass an entire URI as the identifier for the resource I want to update? Does that even make sense? Well, lets first think about how applications identify resources internally.

The most common way for a web application to identify a resource internally is by a primary key in a database table. This key is typically an integer value that is automatically incremented every time a new record is inserted. This key is unique for each record in that table. This makes the primary key of a database table an ideal candidate for using as part of a URI. You'll often see integers as part of a URI, for instance "/user/4352/". There is a good chance that the number is a unique primary key in the database. This uniqueness maps well toURIs because every URI should be unique in one way or another.

One potential problem with using primary database keys in URIs is that different records in different database tables may share the same key. This doesn't necessarily weaken the uniqueness of the URI because it is still referring to a different type of resource. Consider two database records in two different database tables. These records both have the same integer primary key value, 5. TheURIs for these two resources are still unique because they are referring to two entirely different concepts. So the first URI might be "/user/5/" and the second URI might be "/group/5/". But what if you don't care about the resource type?

A canonical URI might be composed of a UUID instead of the primary key of a database table. UUIDs themselves are unique and may refer to any resource. That is, a UUID doesn't need a context in order to be unique. If our above two URIs were to use UUIDs, they might look something like "/user/cadb1d94-5305-11df-98a5-001a929face2/" and "/group/d8eee85c-5305-11df-8d08-001a929face2". As you can see, we really don't need "user" or "group" as part of the URI. We could refer to a resource canonically with something like "/data/cadb1d94-5305-11df-98a5-001a929face2/". This could refer to either a user or a group. This can be both flexible and dangerous.

Having a canonical URI based on a UUID can be flexible because the client requesting the resource doesn't need to know the context. The client might have acquired this URI and has no idea what exactly it is a representation of. Even with just theUUID , the client now has the ability to discover the type of resource this URI is pointing to based on the data it returns. This can also be dangerous for exactly the same reason. If a client doesn't know how to handle the data returned by a canonical URI, chances of the the client malfunctioning are higher. The data representations returned by URI resources are a lot like interfaces; different data types can still provide the same interfaces by having a subset of common keys.

The location part of a URI might also be useful for passing as parameters to web applications. Until now, I've only been talking about the path in which the server must look for the resource. But this is making the assumption that the resource in question still lives on the same server. By only passing primary database keys or UUIDs as parameters, we leave the location aspect out of the equation. It might be more flexible to pass a full URI as a parameter. Even if the URI location is pointing to the same location in which the request arrived. It really isn't a big deal for a server to check when processing requests. If the resource lives here, we simplydissect the URI and process as usual. Otherwise, we forward the request to the appropriate location. I realize I'm oversimplifying this a little too much but the idea is to think about passing wholeURIs as parameters, not so much the details of how we should go about implementing a full-fledged distributed computing platform.

So remember that canonical URIs composed of UUIDs can be useful when treated with care. If context is important, don't use them. Stick to using primary database keys if it helps keep things simple. Try experimenting with a simple web application that will accept a full URI instead of an ID string of some sort. A flexible solution might even accept either or.

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.

jQuery API Attributes

jQuery is an excellent Javascript toolkit for interacting with server APIs. Especially for RESTful, resource-oriented APIs. Each resource returned from such an API generally has a unique ID associated with it. This could be a database primary key or a UUID. Regardless, it is used to uniquely identify the resource so it may be referred to as a URI such as /resource/3495/.

jQuery web applications often build lists of user interface elements from resource lists. For example, /resource/list/ might return a list of resources in the for of (id, name). Once the jQuery callback has this list of id-name pairs, it can build an HTML list. The question is, how should the resource ID be stored in the user interface so that it can be used again as part of a resource URI if the user clicks a list element?

One solution is to store the ID directly in the DOM element when it is created. The benefit here is that the URI can be constructed from the click event. The event object itself has a currentTarget attribute which is our list element. Lets say we stored a uuid attribute as part of the list element. Inside the click event handler, we could do something like jQuery(event.currentTarget).attr("uuid"). This is all we need to build a URI for this specific resource.

Software Maintenance

This entry talks about some of the problems faced by current software maintenance practices. It highlights some of the various maintenance methods used to maintain deployed software. Of course, not many seem to do it right.

Problems arise mainly because of incompatibility between software versions. Typically, the entire software package has a version assigned to it. This includes all the constituent parts of the application such as modules and data structures. What if this individual components were giving a version instead of the whole? Well, there are systems out there in existence that do just that according to the entry.

What about taking this atomic version schema idea to the URIs of RESTful APIs. Indeed, this idea isn't anything new as many APIs support this feature. The main problem faced by web applications when performing server-side upgrades is the cached clients. Javascript that interacts with the URIs on the client's behalf may be stuck using an old API version. This is fine if the API version number is part of the URI. But backward compatibility can only be maintained so far back. This can be dealt with much easier if the expected version is part of the URI. If an unexpected version is requested, a message can be displayed to the client telling them to download a newer client. Alternatively, the new client code could be transparently delivered to the client as a response to using an incorrect version number.

File System Resources

RESTful web services often employ the concept of resources. When reading about RESTful web services, you will often here the term resource or resource-oriented. This is because a key principle of a RESTful system is that of the URI. The unique resource identifier is used to point to some resource, as the name suggests.

The concept of a unique resource identifier says nothing about the context in which it is used. That is, a URI can point to a resource on the web, or it can point to a resource locally on the file system. When using a URI on the local file system, the URIs will only be unique within the local context. For instance, the URI file:///home/ probably isn't unique within the context of the web but would most surely be unique within the local system.

There are two types of resources we are interested in when constructing RESTful applications. There are remote resource that the application might be interested in that live on the web. And, there are local resources the application might be interested in that exist locally within the file system. These two resource types really aren't all that different. The obvious difference of course being the context in which the resource is considered unique. The other difference is at a level lower than that of a RESTful design is how the actual IO functionality is implemented. For instance, you can't perform read operations on remote resource by invoking traditional file system functionality. The same is also true for performing read functionality with remote resources.

One of the similarities between remote resources and local resources is the URI. The URI differs only slightly between the remote resource, typically using HTTP as the protocol, and the local resource which uses a file IO protocol.

Illustrated below is a simple class hierarchy that models a flexible resource. It is flexible in the sense that instantiated resources can be either remote or local in the application.



Here, the base class is Protocol. Inheriting from this class is the base Resource class, with the children resources, File and HTTP. The classes are purposefully incomplete in definition because this hierarchy allows for many implementation variations. The Protocol class is high level and probably serves as an interface. The reason we want to define the Protocol class in the first place is that in this context, where resources may not be using the same protocol, resources may be considered a protocol type.

The Resource class is what should define the higher-level resource functionality. This is where the uniform methods that should be functional for any resource type should be defined. These could map closely to HTTP methods or to some other consistent interface. The File and HTTP class provide the lower level implementations that are invoked by the Resource interface. This enables an application to use resource abstractions, both local and remote, with no regard for context as the behavior can be invoked in a polymorphic way.

RESTful Python Objects.

Designing RESTful resources that behave like the web in this day and age makes for good API design practice. The resulting API has a very high level of simplicity that is sought after and valued by many developers. However, what about the client end? Can they too benefit from this elegant design? They sure can. Just like anything else in software design, APIs can be abused or they can be used as intended. So, why not make the client work similarly to how the resources themselves behave? Better yet, why not make them identical?

This can be achieved by mapping individual resources to Python instances. This makes for a good abstraction mapping. One resource, one Python instance. But this doesn't really help the Python developer if there are "special" methods they need to invoke on the instance just to interact with the actual resource. This instances acts as a proxy and so both the instance data and the instance behavior should be the same as the resource. This can be done by using the following principles:

• The constructor could issue a POST HTTP request to create a new resource using the constructor parameters.
• The attribute retrieval could be overridden to issue a HTTP GET request.
• The attribute setting could be overridden to issue a HTTP PUT request.
• The object deletion functionality could be overridden to issue a HTTP DELETE request.

That's it, the instance can then behave like a regular Python instance and be a RESTful resource at the same time. Mind you, these are just principles and not and ideal implementation, obviously. So, what is needed is an HTTP library of some kind to fully implement each of these methods. There will no doubt be variations to these methods as well. For instance, there is often the requirement of retrieving lists of resources as opposed to a single resource.

The following is a simple example illustrating these principles.

#Example; RESTful Python instances.

class RESTful(object):
   def __init__(self, uri, **kw):
       #Issue a HTTP POST request construct a new resource.
       print "POSTING..."
      
   def __getattr__(self, name):
       #Issue a HTTP GET, possibly a conditional GET to 
       #retrieve the resource attribute.
       print "GETTING..."
      
   def __setattr__(self, name, value):
       #Issue a HTTP PUT request to update the resource
       #attribute.
       print "PUTTING..."
      
   def __del__(self):
       #Issue a HTTP DELETE request to destroy the resource.
       print "DELETING..."
      
class BlogEntry(RESTful):
   def __init__(self, uri, **kw):
       RESTful.__init__(self, uri, **kw)
      
if __name__=="__main__":
   entry=BlogEntry("/blog", title="Hello", body="World")
   entry.body="There"
   body=entry.body