SPIKE: Design API for ASpace Digital Object CRUD

[mikeapp]

Story

As discussed in our meeting #1625, we would like to design an API for Metadata Cloud that will perform create, update, and delete actions for ASpace Digital Object records.

The API should accept only the DCS data required to perform each action. Metadata Cloud will construct the full JSON payload (including constant values, etc.) required by ASpace and perform the actual ASpace API calls.

Mark's documentation of the ASpace API calls can be found in Slack.

Acceptance

• [ ] A document that specifies the new Metadata Cloud API.

[martinlovell]

I have an endpoint in progress on the metadata cloud side. (It does not actually talk to archives space)

Looking for feedback:

PUT is used for update or create, DELETE is used for delete.

Management would issue a PUT whenever a non-private ParentObjct with aspace as the source is saved (maybe after manifest creation.) (Metadata cloud will determine if it needs to update or create the digital object.)

Management would issue a DELETE whenever a ParentObject with aspace as source is deleted, changed to private, or changed from aspace to some other source.

Payload would be a simple JSON object with the necessary information. (Deletes just need the aspaceUri, but may contain all the data.)

An option for implementing it on the Ruby side:

require 'http'

  def mc_put(mc_url, data)
    metadata_cloud_username = ENV["MC_USER"]
    metadata_cloud_password = ENV["MC_PW"]
    HTTP.basic_auth(user: metadata_cloud_username, pass: metadata_cloud_password).put("http://localhost:8080#{mc_url}", json: data)
  end

  def mc_delete(mc_url, data)
    metadata_cloud_username = ENV["MC_USER"]
    metadata_cloud_password = ENV["MC_PW"]
    HTTP.basic_auth(user: metadata_cloud_username, pass: metadata_cloud_password).delete("http://localhost:8080#{mc_url}",json:data)
  end

response = mc_put("/api/aspace/digital_objects", {
    oid:555,
    archivesSpaceUri: "/repositories/11/archival_objects/53432",
    title: "This is the Title",
    childCount: 5,
    thumbnailOid: 557,
    thumbnailCaption: "Image 5"})

puts "Put digital object"
puts response.status
puts response.body

response = mc_delete("/api/aspace/digital_objects", {
        oid:555,
        archivesSpaceUri: "/repositories/11/archival_objects/53432",
        title: "This is the Title"})

puts "Deleted digital object"
puts response.status
puts response.body

Output:

Put digital object
200 OK
{"oid":555,"title":"This is the Title","thumbnailOid":"557","archivesSpaceUri":"/repositories/11/archival_objects/53432","archivesSpaceDigitalObjectUri":"/repositories/11/digital_objects/735649","childCount":5}
Deleted digital object
200 OK
{"result":"ok"}

[martinlovell]

MC Implementation ideas:

ArchivesSpace lists DigitalObjects in it's ArchivalObject json. Each DigitalObject has a created_by property which is available from the ArchivalObject's json.

We could use the created_by property to determine if the digital object was from Metadata Cloud or not. (This would work as long as metadata cloud only creates digital objects for DCS...we'd have to change the implementation if MC ever wanted to create multiple digital objects.)

(If we use created_by it will be more efficient than opening each digital object to determine if it's from MC/DCS because we can identify the correct digital object from the archival_object's json.)

With a delete request, MC could identify the correct digital_object based on the archival_object uri and delete it (if there is one). For a put, it will either identify and update the existing DO, or create a new one.

[martinlovell]

Archives Space Digital Objects API for Metadata Cloud

Overview

The Archives Space Digital Objects API is used to notify metadata cloud when a digital representation of an archival object has been created, updated, or removed.

API Endpoint

Metadata cloud endpoint for Digital Object API calls is /api/aspace/digital_objects.

PUT

Put when a digital object is created or updated. Metadata cloud will either update the existing DCS digital object in archives space or create a new one.

The body of the put is DigitalObject json. (see below)

DELETE

Delete when a digital object is deleted or made private. Metadata cloud will delete the DCS digital object in archives space if it exists.

The body of the delete is DigitalObject json with at least the archiveSpaceUri and oid populated.

DigitalObject Json

{
    oid: 555,
    archivesSpaceUri: "/repositories/11/archival_objects/53432",
    title: "This is the Title",
    childCount: 5,
    thumbnailOid: 557,
    thumbnailCaption: "Image 5"
}        

Usage Notes

• DCS will PUT whenever a non-private ParentObject with Archives Space as the data source is created or updated.
• DCS will DELETE and PUT when the archives space URI changes.
• DCS will DELETE whenever a ParentObject is deleted, has the data source changed from Archives Space, or becomes private.

Issues

• Do we ever have 2 ParentObjects with the same archives space uri? (Swapping aspace URIs may cause this to happen temporarily.)
• If we use jobs, there may be issues if they run out of sequence.

[mikeapp]

Ready to close?

[martinlovell]

Yes. It's ready to close.