Libraries, and where the API ends

Two pieces of code sit at the centre of everything the Preservation API does with a Deposit.

The METS parser and object model (DigitalPreservation.Mets) reads a METS file into a usable object graph and writes one back out. It has to cope with METS from Archivematica, EPrints and Goobi as well as METS the platform wrote itself, all of which lay out their structural maps and file sections differently. Reading and writing are deliberately implemented in different styles, for reasons set out in METS we read and METS we write.

WorkspaceManager (DigitalPreservation.Workspace) merges the two views of a Deposit: the actual tree of files in S3, and the physical structure described by the METS. The result is a combined tree in which each file carries both its real storage entry and its METS entry - or is visibly missing one of them. That structure is what the Preservation API diffs against an Archival Group to produce an Import Job, and what the Pipeline API walks when it folds tool output back into the METS.

Documented separately, later

Both are to be released as standalone libraries - in .NET, with Python equivalents - so that applications can read and write the platform’s METS, and reason about a deposit workspace, without going through the API. Their documentation belongs with those releases, so this page is a signpost rather than a description. A working Python METS parser already exists in the platform’s own iiif-builder service (src/iiif-builder/app/mets_parser/), which reads the same METS files this way.

The class-level detail is deliberately not written out here: it would date faster than anything else on this site, and none of it is needed to use the platform.

Which side of the boundary they sit on

There is a division of labour here that is easy to miss, and it is deliberate.

The Preservation API manages deposits, import jobs, exports and the repository — the lifecycle of preservation. It does not manage the contents of a deposit’s workspace. As the design put it: you can do whatever you like in the S3 space provided by a deposit. Upload new files, rearrange them; most of the work done on a deposit is in S3, placing files. That is why there is no upload route and no folder-creation route — not an omission, but the boundary.

So anything that assembles deposit content is, in this sense, a third party: a digitisation workflow such as Goobi, which uses a Deposit mainly to acquire a working S3 space to assemble files in; a BitCurator workflow that packages up a bag and uploads it; an operator with the AWS CLI. WorkspaceManager is another one. It is not a privileged back door into the API — it is a .NET library for being that third party well: it works directly on the workspace, and it understands the METS file that describes it.

The API is not the only writer

Because of that, a deposit’s METS file can be changed by something other than the API — the Preservation UI does exactly this. It is why every API operation that changes the METS is guarded by an ETag: the guard is there to catch a concurrent writer, and concurrent writers are expected.

What that means in practice

The API does offer some operations on deposit content, because some of them need the API’s own knowledge — adding files to the METS pulls in the tool-output metadata the API has collected, and the diff needs the merged view. But the library’s surface is wider, and these operations have no HTTP equivalent at all:

Only in the library	What it does
CreateFolder	Creates a folder in the workspace and records it in the METS. The UI’s New Folder button.
UploadSingleSmallFile	Puts a file into the workspace. You cannot POST binary content to the API.
SetModsInformation	Sets access conditions, a rights statement, rights suppression, record identifiers and file links on a file or folder. Everything on the access and inheritance side of the UI.
SetLogicalStructMap / RemoveLogicalStructMap	Edits logical structure one range at a time. Over HTTP you can only POST a whole IIIF Manifest back, and only behind a feature flag.
ValidateDepositFileSystem	Checks the cached view of the workspace against what is actually in storage and reports the differences. (Rebuilding it is available over HTTP — that is what GET {id}/filesystem?refresh=true does.)

If you are integrating over HTTP and need one of these, the answer today is to do the equivalent yourself in the workspace and let the API read the result — which is precisely the arrangement the boundary describes.

The same concepts over HTTP

Where the API does cover the ground, that view is documented. If you are trying to understand what the platform does with a deposit and its METS, read these pages rather than the source:

Deposit filesThe file system view and the combined view of a Deposit - the HTTP form of what WorkspaceManager produces.

Editing METSAdding files to the METS, deleting from it, normalising it, and the ETag that guards it.

Import jobsThe diff between the combined tree and the Archival Group, which is what the merge is for.

METSWhat the platform puts in a METS file, what it reads from other people's, and how identifiers work.