Bridge Application

General Operations

Initialize

  • Purpose: Provides all information needed to initialization the Bridge Ingest App
  • Request: POST https://host:port/bridge/init

  • Request Body: JSON in format:

     {
     "originatorEmailAddress" : "<email address>",        # From email address for notifications
     "duracloudEmailAddresses" : ["<email address>"],     # Email address(es) of DuraCloud administrator
     "targetStoreEmailAddresses" : ["<email address>"],   # Email address(es) of preservation store (Chronopolis) administrator 
     "duracloudUsername" : "<duracloud username>",        # DuraCloud user's username
     "duracloudPassword" : "<duracloud password",         # DuraCloud user's password
     "awsAccessKey" : "<aws key>",                        # Access key to AWS, with rights to use SES (for notifications)
     "awsSecretKey" : "<aws secret key>",                 # Secret key to AWS
     "databaseUser" : "<database user>",                  # Bridge database username
     "databasePassword" : "<database password>",          # Bridge database password
     "databaseURL" : "jdbc:mysql://<database instance>:<database port>/<database name>?sessionVariables=wait_timeout=200000",   # Bridge database connection URL
     "clean" : "false",                                   # True to reset database to a clean state, false to maintain data
     "finalizerPeriodMs" : 60000,                         # Frequency of polling, optional, default is 3600000 (1 hour)
     "daysToExpireRestore" : 30                           # Time to wait before clearing restored content
}
 
  • Response Code: 200 (on success)

  • Response Body: JSON:

    {"message" : "success!"}

Version

  • Purpose: Provides the current version of the Bridge App
  • Request: GET https://host:port/bridge/version
  • Response Code: 200 (on success)

  • Response Body: JSON:

    {"version" : "1.0.0"}
Reporting Operations

Get Total Count of Snapshots

  • Purpose: Retrieves the total count of snapshots. Several optional filters (see query parameters) limit the snapshots used to compute the total.

  • Request: GET https://host:port/bridge/snapshot/total/count ? host=(host) & storeId=(storeID) & status=(status)

    • host - (optional) DuraCloud host from which the snapshot(s) originated. This is generally in the form (account).duracloud.org

    • storeId - (optional) Identifier for DuraCloud storage provider from which the snapshot(s) originated.

    • status - (optional) Current status of the snapshot(s). 

      • Possible status values:

        • INITIALIZED

        • TRANSFERRING_FROM_DURACLOUD

        • REPLICATING_TO_STORAGE

        • CLEANING_UP

        • SNAPSHOT_COMPLETE

        • FAILED_TO_TRANSFER_FROM_DURACLOUD

        • ERROR

        • CANCELLED

  • Response Body: JSON:

    {
  "totalCount: 1
}

Get Total Size (bytes) of Snapshots

  • Purpose: Retrieves the total size (bytes) of snapshots. Several optional filters (see query parameters) limit the snapshots used to compute the total.

  • Request: GET https://host:port/bridge/snapshot/total/size ? host=(host) & storeId=(storeID) & status=(status)

    • host - (optional) DuraCloud host from which the snapshot(s) originated. This is generally in the form (account).duracloud.org

    • storeId - (optional) Identifier for DuraCloud storage provider from which the snapshot(s) originated.

    • status - (optional) Current status of the snapshot(s). 

      • Possible status values:

        • INITIALIZED

        • TRANSFERRING_FROM_DURACLOUD

        • REPLICATING_TO_STORAGE

        • CLEANING_UP

        • SNAPSHOT_COMPLETE

        • FAILED_TO_TRANSFER_FROM_DURACLOUD

        • ERROR

        • CANCELLED

  • Response Body: JSON:

    {
  "totalSize: 1000
}

Get Total Files of Snapshots

  • Purpose: Retrieves the total files of snapshots. Several optional filters (see query parameters) limit the snapshots used to compute the total.

  • Request: GET https://host:port/bridge/snapshot/total/files ? host=(host) & storeId=(storeID) & status=(status)

    • host - (optional) DuraCloud host from which the snapshot(s) originated. This is generally in the form (account).duracloud.org

    • storeId - (optional) Identifier for DuraCloud storage provider from which the snapshot(s) originated.

    • status - (optional) Current status of the snapshot(s). 

      • Possible status values:

        • INITIALIZED

        • TRANSFERRING_FROM_DURACLOUD

        • REPLICATING_TO_STORAGE

        • CLEANING_UP

        • SNAPSHOT_COMPLETE

        • FAILED_TO_TRANSFER_FROM_DURACLOUD

        • ERROR

        • CANCELLED

  • Response Body: JSON:

    {
  "totalFiles": 100
}

Get All Totals (count, size, files) of Snapshots

  • Purpose: Retrieves total count, size and files of snapshots. Several optional filters (see query parameters) limit the snapshots used to compute the totals.

  • Request: GET https://host:port/bridge/snapshot/total ? host=(host) & storeId=(storeID) & status=(status)

    • host - (optional) DuraCloud host from which the snapshot(s) originated. This is generally in the form (account).duracloud.org

    • storeId - (optional) Identifier for DuraCloud storage provider from which the snapshot(s) originated.

    • status - (optional) Current status of the snapshot(s). 

      • Possible status values:

        • INITIALIZED

        • TRANSFERRING_FROM_DURACLOUD

        • REPLICATING_TO_STORAGE

        • CLEANING_UP

        • SNAPSHOT_COMPLETE

        • FAILED_TO_TRANSFER_FROM_DURACLOUD

        • ERROR

        • CANCELLED

  • Response Body: JSON:

    {
  "totalCount": 1,
  "totalSize": 1000,
  "totalFiles": 100
}
Ingest Operations

Create Snapshot

  • Purpose: Performs a snapshot action
  • Request: PUT https://host:port/bridge/snapshot/(snapshotId)

    • snapshotId - Identifier of the snapshot

  • Request Body: JSON:

    {
  "host" : "",
  "port" : "",
  "storeId" : "",
  "spaceId" : "",
  "description" : "",
  "userEmail" : ""
}
    • host - DNS host of DuraCloud instance from which snapshot can be taken
    • port - Port on which DuraCloud applications are available
    • storeID - Identifier of Chronopolis staging storage provider on DuraCloud instance
    • spaceID - Identifier of space in which snapshot content resides
    • description - User-supplied description of the snapshot
    • userEmail - User's email address, for notifications
  • Response Code: 200 or 201 on success (201 if snapshot request did not already exist)

  • Response Body: JSON:

    {
  "snapshotId" : "",
  "status": ""
}

List Snapshots

  • Purpose: Retrieves a list of snapshots. Several optional filters (see query parameters) limit the returned list of snapshots.

  • Request: GET https://host:port/bridge/snapshot ? host=(host) & storeId=(storeID) & status=(status)

    • host - (optional) DuraCloud host from which the snapshot originated. This is generally in the form (account).duracloud.org

    • storeId - (optional) Identifier for DuraCloud storage provider from which the snapshot originated.

    • status - (optional) Current status of the snapshot. 

      • Possible status values:

        • INITIALIZED

        • TRANSFERRING_FROM_DURACLOUD

        • REPLICATING_TO_STORAGE

        • CLEANING_UP

        • SNAPSHOT_COMPLETE

        • FAILED_TO_TRANSFER_FROM_DURACLOUD

        • ERROR

        • CANCELLED

  • Response Body: JSON:

    {
  "snapshots" : [
    {
      "snapshotId" : "",  
      "description" : "",
      "status" : ""
    }, 
    ...,
    ...  
  ]
}

List Snapshot Contents

  • Purpose: Retrieves a list of content items which were included in a snapshot

  • Request:  GET https://host:port/bridge/snapshot/(snapshotId)/content ? page=(pageNumber) & pageSize=(pageSize) & prefix=(prefix)

    • snapshotId - Identifier of the snapshot
    • pageNumber - Page number of content listing

    • pageSize - Number of content items to return in a single response

    • prefix - Limit content list to items which begin with this value

  • Response Body: JSON:

{ 
  "contentItems" : [
    { "contentId" : "",
      "contentProperties" : {"" : ""}
    }
  ]
}


List Snapshot History

  • Purpose: Retrieves a list of content items which were included in a snapshot
  • Request: GET https://host:port/bridge/snapshot/(snapshotId)/history ? page=(pageNumber) & pageSize=(pageSize)
    • snapshotId - Identifier of the snapshot
    • pageNumber - Page number of history set
    • pageSize - Number of history items to return in a single response
  • Response Body: JSON:
{ 
  "totalCount" : (Long) # of historyItems
  "historyItems" : [
    { "historyDate" : (Long) epoch time,
      "history" : "${history item string}"
    },
  ]
}


Get Snapshot Details

  • Purpose: Provides the status of a snapshot action
  • Request: GET https://host:port/bridge/snapshot/(snapshotId)
    • snapshotId - Identifier of the snapshot
  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "snapshotId" : "",
  "snapshotDate" : "",
  "status" : "",
  "sourceHost" : "",
  "sourceSpaceId" : "",
  "sourceStoreId" : "",
  "description" : "",
  "contentItemCount" : "",
  "totalSizeInBytes" : ""
}

    Possible values for status:

    • INITIALIZED

    • TRANSFERRING_FROM_DURACLOUD

    • REPLICATING_TO_STORAGE

    • CLEANING_UP

    • SNAPSHOT_COMPLETE

    • FAILED_TO_TRANSFER_FROM_DURACLOUD

    • ERROR
    • CANCELLED

Snapshot Complete

  • Purpose: Enables storage provider (Chronopolis) to notify bridge app that snapshot content has been successfully transferred to preservation storage and can now be removed from the bridge storage area (and DuraCloud)
  • Request: POST https://host:port/bridge/snapshot/(snapshotId)/complete
    • snapshotId - Identifier of the snapshot

  • Request Body: JSON:

    {
  "alternateIds": ["alternate-id-1", "alternate-id-2"]
}

    • A Snapshot can be mapped to zero or more alternate identifiers (e.g. IDs for bags which contain the content in this snapshot).

  • Response Code: 200 (on success)

  • Response Body: JSON: 

    {
  "status" : "SNAPSHOT_COMPLETE",
  "details" : ""
}

Snapshot Error

  • Purpose: Enables storage provider (Chronopolis) to notify bridge app that processing of the snapshot has resulted in an error
  • Request: POST https://host:port/bridge/snapshot/(snapshotId)/error
    • snapshotId - Identifier of the snapshot

  • Request Body: JSON:

    {
  "error": ""
}


  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "status" : "SNAPSHOT_ERROR",
  "details" : ""
}

Restart Snapshot

  • Purpose: Enables restart of snapshots that failed to transfer successfully from DuraCloud.
  • Request: POST https://host:port/bridge/snapshot/(snapshotId)/restart
    • snapshotId - Identifier of the snapshot

  • Request Body: JSON:

    {}


  • Response Code: 202 (on success)

  • Response Body: JSON:

    {
  "status" : "INITIALIZED",
  "description" : ""
}

Cancel Snapshot

  • Purpose: Enables cancellation of a snapshot that is underway. Calls to this method will fail if the snapshot is in the CLEANING_UP or COMPLETE states.
  • Request: POST https://host:port/bridge/snapshot/(snapshotId)/cancel
    • snapshotId - Identifier of the snapshot

  • Request Body: JSON:

    {}


  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "status" : "CANCELLED",
  "description" : ""
}

Snapshot History Update

  • Purpose: Enables storage provider (Chronopolis) to notify bridge app that a snapshot has an "update" to its history. Whether a snapshot was replicated, successfully stored, checksumed, etc... this is the REST call to handle any and all updates to the history of a particular Snapshot.
  • Request: POST https://host:port/bridge/snapshot/(identifier)/history
    • identifier - Either the snapshot ID or an alternate ID (such as a bag ID) which was associated with the snapshot in the Snapshot Complete call

  • Request Body: JSON:

    • Parameters
      • 'history' - single escaped JSON string that can contain a JSON array of objects or strings - the history event we're trying to record
      • 'alternate' - whether the snapshot ID in the URL is the alternate ID or the original snapshot ID.

    • Preferred format (using name/value pairs) 

      {"history": "[ {'key1' : 'value1'},{'key2' : 'value2'} ]", "alternate": "false"}

    • Alternative formats (also supported, but UI display may not be ideal)

      {"history": "[ 'value1', 'value2' ]", "alternate": "false"}
OR 
{"history": "[ {'key1': 'value1'}, 'value2' ]", "alternate": "false"}
OR
{"history": "value1", "alternate": "false"}
  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "snapshot" : {SnapshotSummary},
  "history" : "${the history string that was just inserted}"
}
Restore Operations

Request Snapshot Restore

  • Purpose: Enables user to request a restoration of a snapshot

  • Request: PUT https://host:port/bridge/restore/request

    {
  "host" : "",
  "port" : "",
  "storeId" : "",
  "spaceId" : "",
  "snapshotId" : "",
  "userEmail" : ""
}

    The email address is the address of the requester. This address will be forwarded along with the details of the restore request to the duracloud admins.

  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "description" : ""
}

Restore Snapshot

  • Purpose: Enables user to initiate the restoration of a snapshot

  • Request: PUT https://host:port/bridge/restore 

    {
  "host" : "",
  "port" : "",
  "storeId" : "",
  "spaceId" : "",
  "snapshotId" : "",
  "userEmail" : ""
}
  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "restoreId" : ""
  "status" : ""
}

     Possible value for status (see Get Restore Details)

Restore Complete

  • Purpose: Enables storage provider (Chronopolis) to notify bridge app that a snapshot has been restored to bridge storage.
  • Request: POST https://host:port/bridge/restore/(restoreId)/complete
    • restoreId - Identifier of the restoration
  • Response Code: 200 (on success)

  • Response Body: JSON: 

    {
  "status" : ""
  "details" : ""
}

Get Restore Details

  • Purpose: Provides the status of a restoration action
  • Request: GET https://host:port/bridge/restore/(restoreId)
    • restoreId - Identifier of the restoration
  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "restoreId" : "",
  "snapshotId" : "",
  "status" : "",
  "startDate" : "",
  "endDate" : "",
  "statusText" : "",
  "destinationHost" : "",
  "destinationPort" : "",
  "destinationStoreId" : "",
  "destinationSpaceId" : ""
}

    Possible values for status:

    • INITIALIZED
    • RETRIEVING_FROM_STORAGE
    • STORAGE_RETRIEVAL_COMPLETE
    • VERIFYING_RETRIEVED_CONTENT
    • VERIFYING_SNAPSHOT_REPO_AGAINST_MANIFEST
    • TRANSFERRING_TO_DURACLOUD
    • TRANSFER_TO_DURACLOUD_COMPLETE
    • VERIFYING_TRANSFERRED_CONTENT
    • CLEANING_UP
    • ERROR
    • RESTORATION_COMPLETE
    • RESTORATION_EXPIRED
    • CANCELLED

Restart Restore

  • Purpose: Enables restart of restores that failed to transfer successfully to DuraCloud.
  • Request: POST https://host:port/bridge/restore/(restoreId)/restart
    • restoreId - Identifier of the restore

  • Request Body: JSON:

    {}


  • Response Code: 202 (on success)

  • Response Body: JSON:

    {
  "status" : "STORAGE_RETRIEVAL_COMPLETE",
  "description" : ""
}

Cancel Restore

  • Purpose: Enables cancellation of a restore that is underway. Calls to this method will fail if the restore is in the CLEANING_UP or COMPLETE states.
  • Request: POST https://host:port/bridge/restore/(restoreId)/cancel
    • restoreId - Identifier of the restoreId

  • Request Body: JSON:

    {}


  • Response Code: 200 (on success)

  • Response Body: JSON:

    {
  "status" : "CANCELLED",
  "description" : ""
}
  • No labels

4 Comments

  1. Gad Krumholz

    Initialize

    Is missing one parameter to configure the period at which the Bridge server should try to finalize the snapshots. If not specified, the default of DEFAULT_POLLING_PERIOD_MS = 60*60*1000; (one hour) will be used.

    "snapshotFinalizerPeriodMs": "${bridge.snapshotFinalizerPeriodMs}"

     

    1. Bill Branan

      Thanks Gad, I've added the parameter you noted.

  2. Gad Krumholz

    Snapshot Complete

    Has a typo... it shouldn't say "snapshot has been restored to bridge storage"... looks like a copy/paste mistake (wink)

    1. Bill Branan

      Thanks Gad, I've updated the purpose of the snapshot complete action to better reflect it's actual purpose. Thanks for pointing this out.

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.