Bridge Application
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"}
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 }
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"}
- Parameters
- Response Code: 200 (on success)
Response Body: JSON:
{ "snapshot" : {SnapshotSummary}, "history" : "${the history string that was just inserted}" }
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
- 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" : "" }
4 Comments
Gad Krumholz
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}"
Bill Branan
Thanks Gad, I've added the parameter you noted.
Gad Krumholz
Has a typo... it shouldn't say "snapshot has been restored to bridge storage"... looks like a copy/paste mistake
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.