Bridge Details

Provides information about the Bridge application. Can also be used to verify that the Bridge application is available at the expected URL.

• Request Type: GET
• Request Path: /
• Response Body: JSON
  • bridge-version: The current version of the Bridge application
  • checksum-types-supported: The checksum types that are supported by the Bridge

            {
              "bridge-version" : "1.0.0",
              "checksum-types-supported" : [ "MD5", "SHA-256", "SHA-512" ]
            }
          

• Response Code: 200 (on success)

Expected client(s): Gateway, DDP

Add Account

Allows the DDP to create a new user account in the Bridge. After this call it will be possible for the OTM Gateway to register with the Bridge. This call can also be used to reset the access credentials for an account.

• Request Type: PUT
• Request Path: /account/{account-id}
• Request Path Parameters:
  • account-id: Account identifier
• Response Body: JSON
  • account-id: Account identifier
  • account-username: Credentials to allow calls to the Bridge for this account
  • account-password: Credentials to allow calls to the Bridge for this account

            {
              "account-id" : "university-of-example",
              "account-username" : "example-username",
              "account-password" : "5ecret!"
            }
          

• Response Code: 201 (on success)

Expected client(s): DDP

List Accounts

Allows the DDP to list all accounts known by the Bridge

• Request Type: GET
• Request Path: /account
• Response Body: JSON
  • Account ID: Account identifier

            {
              "university-of-example",    # Account ID
              "example-state-university"  # Account ID
            }
          

• Response Code: 200 (on success)

Expected client(s): DDP

Register

Allows a Gateway to register itself with the Bridge. The information provided in this registration will allow the Bridge to make calls back to the Gateway, such as to pull content listed in a deposit request. This call must be made prior to calls to deposit content. This call may also be made to update the Gateway registration information.

• Request Type: POST
• Request Path: /register
• Request Body: JSON
  • gateway-url: Base endpoint URL where the Bridge can call back to this Gateway API
  • gateway-username: Credentials to allow the Bridge to make calls back to the Gateway API
  • gateway-password: Credentials to allow the Bridge to make calls back to the Gateway API

            {
              "gateway-url" : "https://example.com/gateway",
              "gateway-username" : "example-username",
              "gateway-password" : "5ecret!"
            }
          

• Response Code: 200 (on success)

• In order for a call to this endpoint to be successful an account with associated credentials must already exist in the Bridge. This must have been created in advance by a Bridge administrator (see Add Account).
• This endpoint may be called both to perform an initial registration and to provide updates to registration information. Calls made by the Bridge after a registration update will use the updated details.

Expected client(s): Gateway

Deposit Content

Requests that a set of content be deposited into the DDP

• Request Type: POST
• Request Path: /deposit ? deposit-format=
• Request Query Parameters:
  • deposit-format: (Optional) Format of content being deposited (e.g. "bagit-profile-v1.2")
• Request Body: JSON
  • Filegroup ID: Identifies a filegroup. Filegroups are generic groupings of files that can be used to capture structure such as in a digital object or work.
  • version: The version of a filegroup
  • files: List of files included in the filegroup
  • File ID: Identifies a file within a filegroup
  • size: Size of a file in bytes
  • Checksum: Type of checksum and checksum of the file (a list of supported checksum types are provided in Bridge Details)

            {
              "filegroup-1" : {                                 # Filegroup ID
                "version" : "2019-12-31T23:59:60Z",
                "files" : {
                  "file-1" : {                                  # File ID
                    "size" : "654321",
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                  "file-2" : {                                  # File ID
                    "size" : "654321",
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },                                            # Additional files listed here
                }
              },
              "filegroup-2" : {                                 # Filegroup ID
                "version" : "2019-12-31T23:59:60Z",
                "files" : {
                  "file-3" : {                                  # File ID
                    "size" : "654321",
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                  "file-4" : {                                  # File ID
                    "size" : "654321",
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },                                            # Additional files listed here
                }
              },                                                # Additional filegroups listed here
            }
          

• Response Code: 201 (on success)

• Each filegroup in the request body is considered an independent deposit which can be referred to in subsequent requests by the filegroup identifier.
• The Bridge uses the Gateway's Transfer File endpoint, and the credentials provided in the Register step to retrieve each file.
• Provided filegroup IDs and file IDs must be URL-safe to support the Bridge requesting those files from the Gateway and the reverse in the restore context
• Provided filegroup IDs must not include slash ("/" or "\") characters. File IDs may include slashes.
• There is no guarantee that all filegroups in a single deposit request will be deposited into the DDP at the same time. This allows the Bridge to manage transfers based on available resources (so as to not over-run local disk, for example).
• The Bridge and DDP will consider the version value as opaque and not attempt to assign any meaning to the value.
• Not including "version" in the JSON is acceptable and is functionally the same as "version" : "". This "empty" version is equivalent to any other version.
• When new filegroup versions are deposited, the Bridge may choose to retrieve and submit to the DDP only those files which have changed between versions (based on file ID and checksum).
• The deposit-format parameter allows the depositor to specify the format of the content being deposited. The Bridge implementation may choose to only support deposits of certain types. Agreements between the depositor and the DDP should specify which types are to be used for deposit.
• In the event of deposit or Bridge failure, incomplete deposits may require a resubmission. Systems interacting with the Bridge, such as the Gateway, should support the capability to restart a deposit.

Expected client(s): Gateway

List Deposits

Retrieves a listing of all initiated and in-process deposits. This list includes all deposits that have been requested (via Deposit Content) but have not yet completed the deposit process (which occurs when the DDP calls Complete Deposit)

• Request Type: GET
• Request Path: /deposit ? status=
• Request Query Parameters:
  • status: (Optional) Limit list to deposits with a specific deposit status
• Response Body: JSON
  • Filegroup ID: Identifies the filegroup being deposited
  • version: The version of a filegroup
  • file-count: The number of files in a deposit
  • status: The current deposit status of the deposit
  • details: Additional details about the state of the deposit

            {
              "filegroup-1" : {                     # Filegroup ID
                "version : "2019-12-31T23:59:60Z",
                "file-count" : "2",
                "status" : "ACCEPTED",
                "details" : ""
              },                                    # Additional filegroups listed here
            }
          

• Response Code: 200 (on success)

• List requests made by a depositor will return only those deposits which were initiated by that depositing entity
• List requests made by the DDP (to determine if there are deposits which are ready for processing) will return results for all depositors
• An optional query parameter could be added to allow a DDP to limit the response based on depositor
• This list will grow large if many deposits are initiated at once and may require paged results
• This list will not include all historical deposits, but only those that are in the process of being deposited

Expected client(s): Gateway, DDP

Get Deposit Status

Allows the Gateway to ask for status of a specific deposit

• Request Type: GET
• Request Path: /deposit/{filegroup-id}/status
• Request Path Parameters:
  • filegroup-id: The ID of the filegroup being deposited
• Response Body: JSON
  • Filegroup ID: Identifies the filegroup being deposited
  • version: The version of a filegroup
  • file-count: The number of files in a deposit
  • status: The current deposit status of the deposit
  • details: Additional details about the state of the deposit

            {
              "filegroup-1" : {                     # Filegroup ID
                "version : "2019-12-31T23:59:60Z",
                "file-count" : "2",
                "status" : "ACCEPTED",
                "details" : ""
              }
            }
          

• Response Code:
  • 200 (on success)
  • 404 (if the provided Filegroup ID does not exist in the system)

• This endpoint is intended to provide status on deposits which have not yet completed. The length of time that a deposit in the completed status remains available to query via this endpoint may vary.
• An additional property may be included in the response JSON for completed deposits to provide the Get Content Details URL for this deposit.

Expected client(s): Gateway

Complete Deposit

Allows the DDP to inform the Bridge that a deposit has completed

• Request Type: POST
• Request Path: /deposit/{filegroup-id}
• Request Path Parameters:
  • filegroup-id: Identifier of the filegroup for which deposit has completed
• Response Code: 200 (on success)

Expected client(s): DDP

List Content

Retrieves a list of all deposited filegroup IDs

• Request Type: GET
• Request Path: /list
• Response Body: JSON
  • Filegroup ID: Identifier of deposited filegroup

            {
              "filegroup-1",  # Filegroup ID
              "filegroup-2",  # Filegroup ID
                              # Additional filegroups listed here
            }
          

• Response Code: 200 (on success)

Expected client(s): Gateway

Get Content Details

Retrieves details about a deposited filegroup, including versions and associated files

• Request Type: GET
• Request Path: /list/{filegroup-id}/{file-id}
• Request Path Parameters:
  • filegroup-id: The identifier of the filegroup for which information is requested
  • file-id: (Optional) The identifier of the file for which information is requested
• Response Body: JSON
  • filegroup: Filegroup identifier
  • Version: The version of the filegroup
  • File ID: Identifies a file within a filegroup
  • size: Size of a file in bytes
  • Checksum: Type of checksum and checksum of the file (a list of supported checksum types are provided in Bridge Details)

            {
              "filegroup" : "filegroup-1",
              "2019-12-31T23:59:60Z" : {                      # Version
                "file-1" : {                                  # File ID
                  "size" : "654321",
                  "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                },
                "file-2" : {                                  # File ID
                  "size" : "654321",
                  "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                },                                            # Additional files listed here
              },                                              # Additional filegroup versions here
            }
          

• Response Code: 200 (on success)

• When a file-id is included, the file matching that ID is the only one returned in files list
• Multiple checksums may be returned for each file (e.g. MD5 and SHA-512)
• This list would not include deleted versions or files. A tombstone capability is possible, but not currently part of this specification.
• The checksum type provided is at the discretion of the DDP and may or may not match the checksum type used when content was deposited

Expected client(s): Gateway

Add Audit Event

Update audit index by providing additional audit details

• Request Type: POST
• Request Path: /audit
• Response Body: JSON
  • ID: Identifier of Filegroup or File to which this audit event is to be applied
  • event-type: Type of event
  • event: Event details

            {
              "filegroup-1" : {                        # ID
                "event-type" : "replication",
                "files" : [ "file-1", "file-2", "file-3" ],
                "event" : {
                  "version" : "2019-12-31T23:59:60Z",
                  "timestamp" : "2020-01-01T23:59:60Z",
                  "replicated-to" : "example-storage-node"
                }
              },                                       # Additional events listed here
            }
          

• Response Code: 200 (on success)

• The types of events and expected details of each event type are listed in the Audit Events Appendix
• The Bridge maintains audit details provided through this endpoint as a cache for the DDP to support convenient retrieval. This audit information is expected to remain in the DDP such that a rebuild of this cache could be performed if the Bridge were to fail. The DDP is not required to maintain this data in a format that facilitates easy access, but should be able to provide it upon request to facilitate a rebuild.

Expected client(s): DDP

Get Audit Log

Retrieves an audit history report. The report will list audit events associated with a single file or set of files in a filegroup.

• Request Type: GET
• Request Path: /audit/{filegroup-id}/{file-id}
• Request Path Parameters:
  • filegroup-id: The identifier of the filegroup for which an audit report is requested
  • file-id: (Optional) The identifier of the file for which an audit report is requested. If this is not provided the audit report is requested based on the filegroup-id.
• Response Body: JSON
  • Filegroup ID: Identifies the filegroup for which audit data is requested
  • File ID: Identifies the file for which audit data is requested
  • date: Date and time that the event occurred
  • type: Type of event that occurred
  • details: Details of the event that occurred

            {
              "filegroup-1" : [                           # Filegroup ID
                {
                  "file-1" : [                            # File ID
                    {
                      "date" : "2019-12-31T23:59:60Z",
                      "type" : "replication",
                      "details" : "Replication to the UCSD storage node"
                    },                                    # Additional events for this file listed here
                  ],                                      # Additional files listed here
                }
              ]
            }
          

• Response Code:
  • 200 (on success)
  • 404 (if no audit information exists for the requested Filegroup ID or File ID)

• It may be desirable to provide paged results for large result sets
• The types of events and expected details of each event type are listed in the Audit Events Appendix

Expected client(s): Gateway

Restore Content

Requests that content be made available for restore

• Request Type: POST
• Request Path: /restore
• Request Body: JSON
  • Filegroup ID: Identifies the filegroup from which the file should be restored
  • version: The version of a filegroup from which the file should be restored
  • files: List of files to be restored
  • File ID: Identifies a file to be restored
  • Checksum: Type of checksum and checksum of the file (a list of supported checksum types are provided in Bridge Details). Including the checksum is optional and is used only to verify that the correct file is being restored

            {
              "filegroup-1" : {                                 # Filegroup ID
                "version" : "2019-12-31T23:59:60Z",
                "files" : {
                  "file-1" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                  "file-2" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                }
              },                                                # Additional filegroups listed here
            }
          

• Response Code: 202 (on success)
• Response Body: JSON
  • restore-id: The identifier for this restore action

            {
              "restore-id" : "54321"
            }
          

Expected client(s): Gateway

List Restores

Retrieves a listing of all in-process restores

• Request Type: GET
• Request Path: /restore ? status=
• Request Query Parameters:
  • status: (Optional) Limit list to restore actions with a specific restore status
• Response Body: JSON
  • Restore ID: Identifier for restore action
  • file-count: The number of files to be restored
  • status: The current restore status of the restore action
  • details: Additional details about the state of the restore action
  • expiration: The date on which the restored content will expire (and no longer be available for retrieval). This value may be empty until a restore action completes.

            {
              "restore-1" : {                          # Restore ID
                "file-count" : "12",
                "status" : "COMPLETE",
                "details" : "",
                "expiration" : "2020-12-31T23:59:60Z"
              },                                       # Additional restore actions listed here
            }
          

• Response Code: 200 (on success)

• Use is anticipated by both the Gateway (to check on restore requests) and the DDP (to determine if there are restore requests which are ready for processing)
• Restore IDs returned by this method are those that have been initiated, are in-process, or have completed but not yet expired
• Restored content will only be made available on the Bridge for a limited time. After this time, content will be removed and the status of the restore will be changed to expired.

Expected client(s): Gateway, DDP

Get Restore

Provides details of the restore request to allow the request to be fulfilled by the DDP

• Request Type: GET
• Request Path: /restore/{restore-id}
• Request Path Parameters:
  • restore-id: The identifier of the restore action
• Response Body: JSON
  • Filegroup ID: Identifies the filegroup from which files are to be restored
  • version: The version of a filegroup from which files are to be restored
  • files: List of files to be restored
  • File ID: Identifies a file to be restored
  • Checksum: Type of checksum and checksum of the file. The checksum is only included if it was part of the original restore request.

            {
              "filegroup-1" : {                                 # Filegroup ID
                "version" : "2019-12-31T23:59:60Z",
                "files" : {
                  "file-1" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                  "file-2" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                }
              },                                                # Additional filegroups listed here
            }
          

• Response Code: 200 (on success)

• The response body of this call is expected to be equivalent to the request body from the original Restore Content request

Expected client(s): DDP

Get Restore Status

Allows the repository to ask for status of a specific content restore action

• Request Type: GET
• Request Path: /restore/{restore-id}/status
• Request Path Parameters:
  • restore-id: The identifier of the restore action
• Response Body: JSON
  • file-count: The number of files to be restored
  • status: The current restore status of the restore action
  • details: Additional details about the state of the restore action
  • expiration: The date on which the restored content will expire (and no longer be available for retrieval). This value may be empty until a restore action completes.

            {
              "file-count" : "12",
              "status" : "COMPLETE",
              "details" : "",
              "expiration" : "2020-12-31T23:59:60Z"
            }
          

• Response Code:
  • 200 (on success)
  • 404 (if the provided Restore ID does not exist in the system)

• Restored content will only be made available on the Bridge for a limited time. After this time, content will be removed and the status of the restore will be changed to expired.

Expected client(s): Gateway

Get Restored Content

Allows for the retrieval of restored content from the Bridge

• Request Type: GET
• Request Path: /restore/{restore-id}/{filegroup-id}/{file-id}
• Request Path Parameters:
  • restore-id: The identifier of the restore action
  • filegroup-id: The identifier of the filegroup
  • file-id: The identifier of the file to retrieve
• Response: File stream of the restored file
• Response Headers:
  • Digest: Checksum type and value of the restored file, as defined in RFC3230
  • Content-Length: Size in bytes of the restored file
• Response Code:
  • 200 (on success)
  • 307 (if the requested content is available at an alternative URI, a Location header is required)
  • 404 (if the provided Restore ID, Filegroup ID, or File ID does not exist in the system)

Expected client(s): Gateway

Complete Restore

Allows the DDP to inform the Bridge that a restore has completed

• Request Type: POST
• Request Path: /restore/{restore-id}
• Request Path Parameters:
  • restore-id: Identifier of the completed restore action
• Response Code: 200 (on success)

Expected client(s): DDP

Delete Content

Removes one or more files from DDP storage

• Request Type: POST
• Request Path: /delete
• Request Body: JSON
  • Filegroup ID: Identifies the filegroup from which the file should be deleted
  • version: The version of a filegroup from which the file should be deleted
  • files: List of files to be deleted
  • File ID: Identifies a file to be deleted
  • Checksum: Type of checksum and checksum of the file to be deleted (a list of supported checksum types are provided in Bridge Details). Including the checksum is optional and is used only to verify that the correct file is being deleted

            {
              "filegroup-1" : {                                 # Filegroup ID
                "version" : "2019-12-31T23:59:60Z",
                "files" : {
                  "file-1" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                  "file-2" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  }
                }
              },                                                # Additional filegroups listed here
            }
          

• Response Code: 202 (on success)
• Response Body: JSON
  • delete-id: The identifier for this delete action

            {
              "delete-id" : "54321"
            }
          

• It would be possible to retain enough information to be able to provide a tombstone-type response for File IDs which were at some point in the system but have been removed.
• It would be possible to allow the "files" section to be omitted if all files in a given filegroup version are to be deleted.
• It would be possible to allow the value associated with a filegroup ID to be omitted if all files in all versions of a filegroup are to be deleted. In the provided example, the alternative request would be: "filegroup-1" : {}

List Deletes

Retrieves a listing of all in-process deletes

• Request Type: GET
• Request Path: /delete ? status=
• Request Query Parameters:
  • status: (Optional) Limit list to delete actions with a specific delete status
• Response Body: JSON
  • Delete ID: Identifier for delete action
  • file-count: The number of files to be deleted
  • status: The current delete status of the delete action
  • details: Additional details about the state of the delete action

            {
              "delete-1" : {           # Delete ID
                "file-count" : "7",
                "status" : "ACCEPTED",
                "details" : ""
              },                       # Additional delete actions listed here
            }
          

• Response Code: 200 (on success)

• Use is anticipated by both the Gateway (to check on delete requests) and the DDP (to determine if there are delete requests which are ready for processing)
• Delete IDs returned by this method are only those that have been initiated or are in-process

Expected client(s): Gateway, DDP

Get Delete

Provides details of the delete request to allow the request to be fulfilled by the DDP

• Request Type: GET
• Request Path: /delete/{delete-id}
• Request Path Parameters:
  • delete-id: The identifier of the delete action
• Response Body: JSON
  • Filegroup ID: Identifies the filegroup from which files are to be deleted
  • version: The version of a filegroup from which files are to be deleted
  • files: List of files to be deleted
  • File ID: Identifies a file to be deleted
  • Checksum: Type of checksum and checksum of the file. The checksum is only included if it was part of the original delete request.

            {
              "filegroup-1" : {                                 # Filegroup ID
                "version" : "2019-12-31T23:59:60Z",
                "files" : {
                  "file-1" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                  "file-2" : {                                  # File ID
                    "MD5" : "d41d8cd98f00b204e9800998ecf8427e"  # Checksum
                  },
                }
              },                                                # Additional filegroups listed here
            }
          

• Response Code: 200 (on success)

• The response body of this call is expected to be equivalent to the request body from the original Delete Content request

Expected client(s): DDP

Get Delete Status

Allows the repository to ask for status of a content delete action

• Request Type: GET
• Request Path: /delete/{delete-id}/status
• Request Path Parameters:
  • delete-id: The identifier of the delete action
• Response Body: JSON
  • Delete ID: Identifier for delete action
  • file-count: The number of files to be deleted
  • status: The current delete status of the delete action
  • details: Additional details about the state of the delete action

            {
              "delete-1" : {
                "file-count" : "7",
                "status" : "ACCEPTED",
                "details" : ""
              }
            }
          

• Response Code:
  • 200 (on success)
  • 404 (if the provided Delete ID does not exist in the system)

Expected client(s): Gateway

Complete Delete

Allows the DDP to inform the Bridge that a delete has completed

• Request Type: POST
• Request Path: /delete/{delete-id}
• Request Path Parameters:
  • delete-id: Identifier of the completed delete action
• Response Code: 200 (on success)

Expected client(s): DDP

Deposit Status

All Deposit Endpoints must support the following set of status values. Other status values may be added to this list to provide additional detail about processing activity.

• DEPOSIT_ACCEPTED - The first status value set on a valid deposit action. Indicates that a deposit has been initiated.
• DEPOSIT_STAGED - Indicates when content to be deposited has been retrieved from the Gateway and is available to the DDP for deposit processing.
• DEPOSIT_COMPLETE - The final status value set on a deposit action that has completed successfully. Indicates that all work on the deposit to be done by the Bridge and DDP has completed.
• DEPOSIT_ERROR - Indicates that an error occurred while performing the deposit and processing has halted. Further details should be provided as to the cause of the error.

Restore Status

All Restore endpoints must support the following set of status values. Other status values may be added to this list to provide additional detail about processing activity.

• RESTORE_ACCEPTED - The first status value set on a valid restore action. Indicates that a restore has been initiated.
• RESTORE_STAGED - Indicates when content to be restored has been collected from the DDP and is available for the Gateway to retrieve.
• RESTORE_COMPLETE - The final status value set on a restore action that has completed successfully. Indicates that all work on the restore to be done by the Bridge and DDP has completed.
• RESTORE_ERROR - Indicates that an error occurred while performing the restore and processing has halted. Further details should be provided as to the cause of the error.

Delete Status

All Delete endpoints must support the following set of status values. Other status values may be added to this list to provide additional detail about processing activity.

• DELETE_ACCEPTED - The first status value set on a valid delete action. Indicates that a delete has been initiated.
• DELETE_COMPLETE - The final status value set on a delete action that has completed successfully. Indicates that all work on the delete to be done by the Bridge and DDP has completed.
• DELETE_ERROR - Indicates that an error occurred while performing the delete and processing has halted. Further details should be provided as to the cause of the error.