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.
/values
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-listis a list of(tag . value)conses)(delete-objects-tag-values query tags-list)— delete the tag values on all object matching the given query
/about
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.