JSON API Introduction

(⬑JSON API Index)

Jump to:


In September, 2011, Fossil contributor Stephan Beal had the great pleasure of meeting D. Richard Hipp, Fossil's author, for lunch in Munich, Germany. During the conversation Richard asked, "what does Fossil need next?" Stephan's first answer was, "refactoring into a library/client, as opposed to a monolithic app." We very quickly agreed that the effort required would be "herculean," and second choice was voiced, "a JSON API." They briefly discussed the idea and Richard gave his blessing. That night work began.

Why a JSON API? Because it is the next best thing to the "librification" of Fossil, in that it makes Fossil's features available to near-arbitrary applications using a simple, globally available data format.

Building JSON Support

In environments supported by fossil's configure script, simply pass --enable-json to it:

$ ./configure --prefix=$HOME --enable-json ...

When built without that option, JSON support is disabled. When reconfiguring the source tree, always be sure to do a "make clean" (or equivalent for your platform) between builds (preferably before reconfiguring), to ensure that everything is rebuilt properly. If you fail to do that after enabling JSON on a tree which has already been built, most of the sources will not be rebuilt properly. The reason is that the JSON files are actually unconditionally compiled, but when built without --enable-json they compile to empty object files. Thus after a reconfigure the (empty) object files are still up-to-date vis-a-vis the sources, and won't be rebuilt.

To build Fossil with JSON support on Windows using the Microsoft C compiler:

cd win
nmake -f Makefile.msc FOSSIL_ENABLE_JSON=1

It has been seen to compile in VC versions 6 and higher.

Goals & Non-goals

The API described here is most certainly not REST-conformant, but is instead JSON over HTTP. The error reporting techniques of the REST conventions (using HTTP error codes) "does not mesh" with my ideas of separation of transport- vs. app-side errors. Additionally, REST requires HTTP methods which are not specified by CGI (namely PUT and DELETE), which means we can't possibly implement a REST-compatible interface on top of fossil (which uses CGI mode even for its built-in server).

The overall goals of this effort include:

The non-goals include:

Adding JSON support also gives us a framework off of which to build/enhance other features. Some examples include:

Potential Client-side Uses

Some of the potential client-side uses of this API include...

Technical Problems and Considerations

A random list of considerations which need to be made and potential problem areas...