Why Maintain the API as an Independent Product?

A retrospective consideration of over six years of development in the Fedora Commons 3 ecosystem (repository and related application platforms) suggests two broad cases for managing a common repository REST API as a separate product: One emerging from concerns of the Fedora Commons 3 and 4 developers, and one from the broader community of projects and institutions building projects around Fedora Commons and related products.

The Community Case

The institutions and communities served by the Fedora Commons software products are diverse, but  they have in common investments in transparency, data mobility, and flexible software integrations. Rather than the elaboration of a boutique API bound to a particular implementation of Fedora, we feel these community interests would be best served by an independent, conformance-testable APIs designed as extensions to more general API specification.

From its inception, the Fedora Commons project has been an attempt to overlay linked data descriptions on stored or linked binary assets. Fedora Commons has never been the sole product in this space, and this more general case has evolved into the Linked Data Platform Specification, a W3C standard that describes much of what Fedora Commons provides at the API level. Given the broader audience for and tooling around this specification, the Fedora developers have elected to make it the basis for a common repository REST API. Building around an independent API based on broader standards will allow the community more security and flexibility: The ecosystem of software around the API will be able to apply to more sources of data, back-end migration may be possible with less disruption to running applications, and the likelihood of third-party tools being applicable to an institution's data will be greater.

The Developer Case

Over the course of Fedora Commons 3.x, there were four related concerns tracked under a single version number:

1. The web APIs, both REST and SOAP
2. The FOXML serialization format for stored objects (and interpretive software thereof)
3. The Java interfaces for the Fedora Commons 3 modules
4. The repository configuration (fcfg markup and Fedora "home" directory)

The collection of all these concerns under a single compatibility promise was an impediment to development and contributed to a slow release cycle both for bugfixes and for adaptations to a more rapidly changing technology landscape. Going forward, the developers believe that partitioning these concerns will facilitate a more nimble and manageable development lifecycle for current iterations of Fedora Commons.

Groups of Work

There are several major groups of work created as a result of review and discussion around Fedora's HTTP API. It is important to understand that all of this work assumes the plan of API partitioning as developed by the TWG.

1. Partition the APIs
   1. This piece of work comprises the construction of fully-specified API modules as outlined in the partition plan. These specifications must be of such detail and precision as to enable a complete reimplementation of the APIs they describe without reference to the Fedora implementation code. This work includes the definition of optional API modules and their advertisement, conformance levels, and an accompanying conformance test suite.
2. Partition the ontologies
   1. This piece of work parallels the previous item. It entails the processing of the current Fedora ontologies to partition them in line with the partition of the API itself.
3. Partition the code
   1. This piece of work requires massive changes to the current implementation code. It will require breaking apart fcrepo-http-api into multiple modules that each support a separate Fedora API module