FluidDB Objects in 10 Minutes

When looking at FluidDB‘s tags (see FluidDB Tags in 10 Minutes), we briefly touched upon FOM‘s Object class (not to be confused with Python’s native object class). I instantiated an object representing the planet Mars:

>>> from fom.mapping import Object
>>> mars = Object(about="planet:Mars")
>>> mars
<Object planet:Mars>

The thing to note is that I supplied the about keyword. By instantiating this way, I have no way of knowing if it existed before or not – the appropriate FluidDB object is created if one doesn’t exist already. In the big scheme of things it probably doesn’t matter, but it’s important to be aware.

The about keyword sets the value of a useful tag that is often assigned to objects when created: fluiddb/about. The about tag is used to label an object with something descriptive. It can be anything, but certain conventions are slowly evolving amongst FluidDB developers and users.

For example, an application I am developing uses the convention “band:<band name>” to label an object as representing a particular musical band. Nicholas J Radcliffe has written more on the subject on his About Tag blog which is a recommended read.

Let’s take a look at that tag:

>>> mars.get("fluiddb/about")
('planet:Mars', 'application/vnd.fluiddb.value+json')

An optional about tag is very useful but not all objects have, or indeed need, one. Fortunately, we can also refer to any object by its unique GUID which is guaranteed to exist:

>>> mars.uid
'276da99e-c8d9-42c9-99ae-3db69a5e9ef0'

If I wanted to load an object by its GUID, I simply supply the uid parameter (it’s a good job I know the ID!):

>>> red_planet = Object( uid='276da99e-c8d9-42c9-99ae-3db69a5e9ef0' )
>>> red_planet
<Object planet:Mars>
>>> red_planet.get("fluiddb/about")
('planet:Mars', 'application/vnd.fluiddb.value+json')

Tags form the real power of FluidDB, so it’s important to be able to determine what tags have been added to an object. Let’s take our Mars example first:

>>> red_planet.tag_paths
['metaljoe/foo', 'fluiddb/about']
>>> red_planet.tags
[<fom.mapping.Tag object at 0x57edb0>, <fom.mapping.Tag object at 0x57fd10>]

The first attribute stores the tag names, while the second returns these tags instantiated as FOM Tag objects. We can check they are indeed proper Tag instances by peeking at the descriptions:

>>> [ tag.description for tag in red_planet.tags ]
['behold: the foo tag', 'A description of what an object is about.']

I can also test for the presence of a tag by using the has() method:

>>> red_planet.has( "metaljoe/foo" )
True
>>> red_planet.has( "the_mekon/likes" )
False

URLs were briefly mentioned in an earlier post about tags – each tag has a corresponding URL. FluidDB’s RESTful API means each object in the system also has a unique URL. For example, on the FluidDB sandbox instance our planet:Mars object can be referenced by the URL http://sandbox.fluidinfo.com/objects/276da99e-c8d9-42c9-99ae-3db69a5e9ef0 – pointing your browser to that URL returns a little bit of JSON:

{"tagPaths": ["metaljoe\/foo", "fluiddb\/about"]}

An object’s tags can also be referenced via URLs. For example, the fluiddb/about tag is referenced by the following URL:

http://sandbox.fluidinfo.com/objects/276da99e-c8d9-42c9-99ae-3db69a5e9ef0/fluiddb/about

Which yields the contents of the tag for that object:

"planet:Mars"

Note that a browser will be making GET requests to these resources. Being RESTful, we can make full use of different HTTP methods (GET, PUT, POST, DELETE) to perform reading, creating, updating and deleting of our FluidDB resources, but that’s a subject for another time.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s