Madoc handoff protocol

[stephenwf]

What is a handoff?

A handoff is when an external service or deployed application is used to edit a resource or set of resources that live inside madoc without directly calling Madocs APIs. For example, I could develop a standalone tool for reordering the canvases inside of a manifest. Since my tool works with IIIF, the input is a IIIF manifest and the output is a IIIF manifest - with the canvases reordered. This protocol would allow the transaction of Manifest -> Manifest or Canvas -> Canvas to an external tool and then derive the changes that were made and save them to Madoc.

A high level of the steps involved:

1. Transfer out
The first step would be the transfer of the IIIF resource from Madoc to the external tool. Madoc could at this point lock part of the IIIF resource to prevent conflicts. The tool would receive the IIIF resource in some way.

2. Modification
This step happens in the tool, the IIIF is modified in some way.

3. Transfer in
The IIIF resource that was modified is transferred back to Madoc in some way.

4. Approval
The changes made are summarised inside of Madoc and the atomic operations are approved or rejected (this could be automatic or manual)

5. Commit
The atomic changes are applied.

Mechanics of the protocol

There are various decisions on how this should be implemented and considerations for how easy this will be for users to use these external tools and how easy it will be for developers to create new tools.

• How Madoc transfers IIIF out to a service (HTTP endpoint?)
• What modifications are supported and how to detect these changes and map them to atomic Madoc APIs
• How to manage deletions from external tools and how to inform users before the commit phase.
• How to display the summary of what has changed clearly - may be different per atomic change
• How an external tool posts back the modified resource (callback / API call / redirect / postMessage)

Example: label editor. In order to support an external label editor we would need the following inside of Madoc:

Before:

{
  "label": {"en": ["Initial label"]},
   ...
}

After:

{
  "label": {"en": ["Another label"]},
   ...
}

• A way to detect changes to labels
• A way to display the label changes in the summary
• A way to convert the new label changes to atomic madoc APIs

This would be similar for any other changes and each would have to be implemented. This could be done over time, expanding the protocol and supported modifications that can be done outside of Madoc and reimported safely.

Potential use-cases

This is still a work in progress

• Sorting room - splitting up large manifests into smaller manifests
• Upgrading image resources - taking a IIIF resource with a single large image, generating a IIIF image service endpoint and updating
• Enrichment pipeline - handing off to a backend that will attach new seeAlso linking properties with enriched data or annotations
• Geo-rectification - handing off to a service that will return an annotation to align a historical map to modern co-ordinates