An update to cl-fluiddb

qr-code for this page's url

About two weeks ago the Fluidinfo people release the long awaited update to the Fluiddb API. You may want to read the blog posts: here or here or look at the API documentation itself.

As I maintain two libraries that aid in the use of this API, some work was required. I started with cl-fluiddb the Common Lisp library. (The emacs lisp library will come later and should track the changes made to cl-fluiddb described here).

Forgotten functions added

After reviewing the API docs it became clear that some functions were missing. This is not new functionality, just some I never needed and hadn't even noticed was missing. The two new functions are offering the HEAD and DELETE verbs for object tag values:

  • (object-tag-has-value-p id tag)
  • (delete-object-tag-value id tag)

New functions

The November update brought two new features: /values and /about.


With /values you can perform operation on multiple objects at the same time. The new functions are:

  • (query-objects-tag-values query tags-list) - retrieve multiple tag values for all object matching the given query
  • (set-objects-tag-values query tags-values-list) - set multiple the tag values on all object matching the given query (tags-values-list is a list of (tag . value) conses)
  • (delete-objects-tag-values query tags-list) — delete the tag values on all object matching the given query


With /about you can access an object via its about tag rather than its id. This not only makes for readable URLs for fluiddb based web apps but can also simplify your code as you don't have to first find the id of a object before adding a tag etc.

The new functions are fairly straightforward. E.g. instead of get-object which requires an id as a parameter you now also have get-object-about which instead take a string with the about tag.

The newly added functions for the /about functionality are:

  • (get-object-about about)
  • (get-object-about-tag-value about tag &key want-json accept)
  • (set-object-about-tag-value about tag content &optional content-type)
  • (object-about-tag-has-value-p about tag)
  • (delete-object-about-tag-value about tag)

Interface changes for better consistency

While doing all these additions it also occurred to me that the cl-fluiddb API was inconsistent in its treatment of tag names. Some functions expected two arguments (a namespace and a tag name) while others only one (a string with namespace and tag name). So in this revamp I made a backward incompatible change to only use the single argument way of specifying a tag. (The one exception remain create-tag and create-namespace which actually put the name of the tag or namespace to be created in the request body not the URL.)

Format of namespaces and tags

Now that all functions have a unified way of passing namespaces and tags, there is also a generalised way how these can be expressed. cl-fluiddb now exposes the new (url-format-namespace-or-tag data) generalised function which you can add a method to in order to format your choice of name representation into a string that will be used in the path part of the URL (i.e. 'funny' characters have to be properly URL escaped in the returned string). Once defined you can pass that type as a namespace or tag parameter to all functions. Currently there are methods for strings and lists (of strings). So now you can e.g. say either (get-object-about-tag-value "isbn:xyz-xyz..." "hdurer/general/rating") or (get-object-about-tag-value "isbn:xyz-xyz..." '("hdurer" "general" "rating")).

All these changes are now in the cl-fluiddb github repository.