Recipes

Small answers to specific questions. Each one links to the page that explains it properly, for when the answer is not quite what you needed.

All of these assume the headers from the Quickstart: a bearer token and X-Client-Identity.

Reading

What is at this path?

GET /repository/my-collection/my-object
GET /repository/my-collection/my-object?view=lightweight                 # without the file listing
GET /repository/my-collection/my-object?view=lightweight&version=v2      # as it was at v2

version is only allowed with view=lightweight; any other combination is a 400. On a Container or Binary use the Memento timestamp rather than v2. Repository

Give me the object’s METS.

GET /repository/my-collection/my-object?view=mets

Returns the XML. Repository

What versions does it have, and what changed in each?

GET /repository/my-collection/my-object          # the versions list is a property of the object
GET /ocfl/storagemap/my-collection/my-object     # what each version holds, and where

There is no /versions route: versions is a property on the Archival Group itself. Versions and the Storage Map

Which deposits have touched this object?

GET /deposits?archivalGroupPath=my-collection/my-object&showAll=true

A value containing / matches the whole path; one without matches any path ending in it. Deposits

What has changed in the repository lately?

GET /activity/archivalgroups/collection      # then follow last, and page backwards

Activity Stream

Find an object from a catalogue identifier.

GET /search?text=MS%202249&pageNumber=0

Paging is pageNumber, from 0. Search

Working on a deposit

Add one file to a large object, without exporting it.

Create a deposit against the existing object without export, put just the new file in it, add it to the METS, and run the diff. The deposit’s METS arrives from the object, so the diff sees everything else already present and adds only your file.

POST /deposits          {"type":"Deposit","archivalGroup":"…/my-object","template":"RootLevel"}
# upload objects/new-page.tif to the deposit's files prefix
GET  /deposits/{id}                                          # for metsETag - the POST above has none
POST /deposits/{id}/mets            If-Match: <metsETag>     ["objects/new-page.tif"]
POST /deposits/{id}/importjobs      {"id":"…/deposits/{id}/importjobs/diff"}

No separate filesystem?refresh=true is needed: adding to the METS re-reads the workspace itself. Update without an export

See what the import job would do, before doing it.

GET /deposits/{id}/importjobs/diff

Generating a diff does not run it, and you can read it as often as you like — until a job has run from the deposit, after which both answer 409. Import Jobs

What is actually in my deposit?

GET /deposits/{id}/filesystem?refresh=true

refresh=true re-reads S3. Without it you get the cached view, which will not show files you have just uploaded. Deposit files

What does the platform know about my files?

Each file in that response carries a metadata list — digests, PRONOM identification, EXIF, virus scan results — collected from tool outputs in the deposit.

Have the platform identify formats and scan for viruses.

POST /deposits/{id}/pipeline
GET  /deposits/{id}/pipelinerunjobs

The run adds the files under objects/ to the METS itself, so there is nothing further to do unless you added files after it started. Tool outputs and pipelines

Abandon a deposit.

DELETE /deposits/{id}

Removes the record and empties its workspace. Does nothing to an object already preserved from it. Deposits

When something has gone wrong

My import job failed. What now?

The deposit goes to status error and becomes inactive. Read the errors on the result, then:

PUT /deposits/{id}/activate

to pick it up again. You cannot run a second import job from a deposit whose first one succeeded — that needs a new deposit. Import Job results

Show me everything that has failed.

GET /deposits?status=error&showAll=true

My If-Match keeps being rejected.

Re-read the deposit and use its metsETag. It is null in the response to creating a deposit, and it changes on every successful write, so it goes stale between edits. Editing METS

I get 409 creating a deposit for an object.

There is already an active deposit for it. Find it and finish or delete it:

GET /deposits?archivalGroupPath=my-collection/my-object

I get 409 saying ancestors must exist.

PUT /repository/a/b needs a to exist already. Create the parents first, top down. Creating a Container