Page History

...

• Purpose: Allows the repository to send content to the Bridge for deposit into the DDP
• Request: POST /bridge/deposit ? {checksum-type}
  • checksum-type: (Optional) Applies to all file checksums (can be one of: MD5, SHA-256, SHA-512). Default is MD5.

• Request Body: JSON 

  Code Block
  language js
  { "objectfilegroup-1-id" : { "file-1-id" : "file-1-checksum", "file-2-id" : "file-2-checksum" }, "object-2-id": { # filegroup "file-3is a generic grouping of files that can be used to capture structure such as in a digital object or work "file-1-id" : "file-1-checksum", "file-42-id" : "file-2-checksum" } }

• Response Code: 201 (on success)

• Response Body: JSON 

  Code Block
  { "deposit, "filegroup-2-id" : { "file-3-id" : "file-1-checksum", "file-4-id" : "file-2-checksum" } }

  
  

• Response Code: 201 (on success)

• Response Body: JSON 

  Code Block
  { "deposit-id" : "" }

  
  

• Notes:

  Notes:

  • There is an explicit expectation that the content to be deposited will be available from the OTM Gateway at the path: "gateway-url" + / + "file-id". How the Gateway resolves the file stream based on a request to this URL is irrelevant to the Bridge.
  • Provided Filegroup IDs and File IDs must be URL-safe to support the Bridge requesting those files from the OTM Gateway and the reverse in the restore context

  • There is no guarantee that all files 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).

  • This does not currently allow for deposits where files use differing checksum types. Is this a necessary use case?
  • This does not currently provide a method for grouping files (e.g. to specify all files in a "work"). Is there a need to capture groupings within the Bridge or DDP?

...

• Purpose: Retrieves a listing of all in-process deposits
• Request: GET /bridge/deposit ? {status}
  • status: (Optional) Limit list to deposits in a specific status

• Response Body: JSON 

  Code Block
  { "deposit-id-1" : { "filesfilegroups" : "", # Number of filesfilegroups in deposit "statusfiles" : "", # Current deposit status # Number },of files in deposit "status" : "" # Current deposit status }, # Additional deposits listed here }

  
  

• Response Code: 200 (on success)
• Notes:
  • Used by both the OTM Gateway (to check on submitted deposits) and the DDP (to determine if there are deposits which are ready for processing)
  • The deposits returned by this method are only those that are in-process (possibly including those that have recently completed). There is no expectation that information about deposits that have completed successfully or were aborted will be available as part of this call indefinitely, as the deposits themselves are not intended to be the item of record. Information about files in completed deposits can be found by requesting an audit history report (below). Are there use cases that would require longer-term access to completed deposits via this endpoint?

...

• Purpose: Allows the repository to ask for status of a given deposit
• Request: GET /bridge/deposit/{deposit-id}

• Response Body: JSON

  Code Block
  { "deposit-id" : "", "status" : "", # Value based on defined set of known status states # There could be more information here, like an approximate percentage completion of the current step, if known }

  
  

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

Abort Deposit

• Notes:
  • It would be possible to retain enough information to be able to provide a tombstone-type response for deposit IDs which were at some point in the system but have been removed

Abort Deposit

• Purpose: Allows the repository to ask the Bridge to abort the deposit Purpose: Allows the repository to ask the Bridge to abort the deposit process
• Request: DELETE /bridge/deposit/{deposit-id}
• Response Codes:
  • 200 (on success)
  • 404 (if the provided Deposit ID does not exist in the system)
  • 403 (if the Deposit is not in a state which allows an Abort action to be applied)

• Response Body: JSON

  Code Block
  { "details" : "", # In the event of a rejected call, information about why the call could not be performed will be provided here }

  
  

• Notes:
  • Only valid when deposits are in certain states (to be better defined as those states are clarified). An Abort will not be allowed if it cannot be performed cleanly by the Bridge

...

• Purpose: Removes one or more files from DDP storage
• Request: POST /bridge/delete ? {checksum-type}   # Using POST rather than DELETE, allows for deleting multiple files (and is consistent with Restore action)
  • checksum-type: (Optional) if provided, applies to all file checksums (can be one of: MD5, SHA-256, SHA-512). Default is MD5.

• Request Body: JSON 

  Code Block
  { "file-1-id" : "file-1-checksum", # Checksum is optional, can be included to verify correct file is being deleted "file-2-id" : "file-2-checksum" }

  
  

• Response Code: 202 (on success)

• Response Body: JSON 

  Code Block
  { "delete-id" : "" }

  
  

• Notes:
  
  • In the versioning scenario, checksum may be used to select which version to delete. If no checksum is provided can either assume most recent version or all versions.

List Deletes

• • 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.
  • Is there any reason/need to specify the Filegroup for each file to be deleted? 

List Deletes

• Purpose: Retrieves a listing of Purpose: Retrieves a listing of all in-process deletes
• Request: GET /bridge/delete ? {status}
  • status: (Optional) Limit list to deletes actions with a specific status

• Response Body: JSON 

  Code Block
  { "delete-id-1" : { "files" : "", # Number of files in delete action "status" : "" # Current delete status }, # Additional delete actions listed here }

  
  

• Response Code: 200 (on success)
• Notes:
  • Used by both the OTM Gateway (to check on delete requests) and the DDP (to determine if there are delete requests which are ready for processing)
  • Similar to deposits, delete IDs returned by this method are only those that are in-process.

...

Abort Delete - ?

Restart Delete - ?

...

List Deposited Content

• Purpose: Asks that an audit history report be generated. If a set of File IDs are provided, the report will list audit events associated with those files. If a set of deposit, restore, or delete IDs are provided, those will each be resolved to a set of File IDs and those files will be in the resulting report.
• Request: POST /bridge/audit ? {id-type}
  • id-type: (Optional) Specifies the type of ID provided in the request body. All IDs must be of the same type. Allowed values are: file, deposit, restore, or delete. Default value is file.

Request Body: JSON 

Code Block
{ "id-1", "id-2", ... }

• Response Code: 202 (on success)

Response Body: JSON 

Code Block
{ "audit-report-id" : "" }

Get Audit History Report

...

Response Body: JSON 

{
  "file-1-id" : {
    "audit-event-1",
    "audit-event-2",
  },
}

...

• Events associated with a deposit, restore, or delete should include the appropriate deposit, restore, or delete ID as part of the audit event
• A format for audit events will need to be defined to support processing of these events.
• Audit reports will be retained by the Bridge for some pre-defined length of time (TBD), after which they will be purged and a new report request would be required

Restore Content

...

• checksum-type: (Optional) if provided, applies to all file checksums (can be one of: MD5, SHA-256, SHA-512). Default is MD5.

Request Body: JSON 

{ 
  "file-1-id" : "file-1-checksum",    # Checksum is optional, can be included to verify correct file is being restored
  "file-2-id" : "file-2-checksum"
}

...

Response Code: 202 (on success)

Response Body: JSON 

{
  "restore-id" : ""
}

...

• In the versioning scenario, checksum may be used to select which version to restore. If no checksum is provided most recent version is assumed.

• Retrieve a list of all deposited files. There are 4 list options, (1) List all filegroups and associated files (2) List all filegroups, no files (3) List all files, no filegroups (4) List only files for the specified filegroup
• Request: GET /bridge/list ? {list-type} & {filegroup}
  • list-type: (Optional) Valid values are "all", "filegroups", and "files". Default is "all"
  • filegroup: (Optional) Indicates that only files for this specific filegroup should be listed

• Response Body: JSON

  Code Block
  language js
  { "filegroup-1-id" : { # filegroup is a generic grouping of files that can be used to capture structure such as in a digital object or work "file-1-id", "file-2-id", }, # Additional filegroups listed here }

  
  

  or

  Code Block
  { "filegroup-1-id", "filegroup-2-id", ... }

  or

  
  

  Code Block
  { "file-1-id", "file-2-id", ... }

  
  

• Notes
  • There are varying options here. May need to consider the actual use cases and needs to see if all of these options are required

Restore Content

• Purpose: Requests that content be made available for restore
• Request: POST /bridge/restore ? {checksum-type}
  • checksum-type: (Optional) if provided, applies to all file checksums (can be one of: MD5, SHA-256, SHA-512). Default is MD5.

• Request Body: JSON 

  Code Block
  { "file-1-id" : "file-1-checksum", # Checksum is optional, can be included to verify correct file is being restored "file-2-id" : "file-2-checksum" }

  
  

• Response Code: 202 (on success)

• Response Body: JSON 

  Code Block
  { "restore-id" : "" }

  
  

• Notes:
  
  • In the versioning scenario, checksum may be used to select which version to restore. If no checksum is provided most recent version is assumed.
  • Is there any reason/need to specify the Filegroup for each file to be restored?

List Restores - ?

Restore Status

• Purpose: Allows the repository to ask for status of a content restore action
• Request: GET /bridge/restore/{restore-id}

• Response Body: JSON 

  Code Block
  { "status" : "" } # This could include a top level status or a per-file status (or both)

  
  

• Response Code: 200 (on success)
• Notes:
  • It may be useful to provide a listing of the files that can be retrieved based on this restore request in the response (not assuming that the original requester of the restore kept that list around from the initial call).
  • 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.

Abort Restore - ?

Restart Restore - ?

Get Restored Content

• Purpose: Allows the repository to retrieve restored content from the Bridge
• Request: GET /bridge/restore/{restore-id}/{file-id} ? {checksum-type}
  • checksum-type: (Optional) Defines the type of checksum to be included in the response ETag header. Can be one of: MD5, SHA-256, SHA-512. Default is MD5.

• Response: Restored file content stream

• Response Codes:
  • 200 (on success)
  • 404 (if the file is not part of the restore or the restored content has expired)
• Response Headers: ETag

Request Audit History Report

• Purpose: Asks that an audit history report be generated. If a set of File IDs are provided, the report will list audit events associated with those files. If a set of filegroup, deposit, restore, or delete IDs are provided, those will each be resolved to a set of File IDs and those files will be in the resulting report.
• Request: POST /bridge/audit ? {id-type}
  • id-type: (Optional) Specifies the type of ID provided in the request body. All IDs must be of the same type. Allowed values are: filegroup, file, deposit, restore, or delete. Default value is file.

• Request Body: JSON 

  Code Block
  { "id-1", "id-2", ... }

  
  

• Response Code: 202 (on success)

• Response Body: JSON 

  Code Block
  { "audit-report-id" : "" }

  
  

Get Audit History Report

• Purpose: Retrieves an audit report that was requested previously via a call to the Request Audit History Report endpoint. 
• Request: GET /bridge/audit/{audit-report-id}

• Response Body: JSON 

  Code Block
  { "file-1-id" : { "audit-event-1", "audit-event-2", }, }

  
  

• Response Codes:
  • 200 (on success)
  • 404 (if there is no audit report with the provided ID)
• Notes:
  • Events associated with a deposit, restore, or delete should include the appropriate deposit, restore, or delete ID as part of the audit event
  • A format for audit events will need to be defined to support processing of these events.
  • Audit reports will be retained by the Bridge for some pre-defined length of time (TBD), after which they will be purged and a new report request would be required

List Restores - ?

Restore Status

...

Response Body: JSON 

{ "status" : "" }   # This could include a top level status or a per-file status (or both)

...

• It may be useful to provide a listing of the files that can be retrieved based on this restore request in the response (not assuming that the original requester of the restore kept that list around from the initial call).
• 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.

Abort Restore - ?

Restart Restore - ?

Get Restored Content

• Purpose: Allows the repository to retrieve restored content from the Bridge
• Request: GET /bridge/restore/{restore-id}/{file-id} ? {checksum-type}
  • checksum-type: (Optional) Defines the type of checksum to be included in the response ETag header. Can be one of: MD5, SHA-256, SHA-512. Default is MD5.

• Response: Restored file content stream

• Response Codes:
  • 200 (on success)
  • 404 (if the file is not part of the restore or the restored content has expired)
• Response Headers: ETag

Bridge API - Endpoints to be used by DDP

...