Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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
    languagejs
    {
      "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-1-checksum",
        "file-2-id" : "file-2-checksum"
      },
      "filegroup-2-id" : {
        "file-3-id" : "file-1-checksum",
        "file-4-id" : "file-2-checksum"
      }
    }


  • Response Code: 201 (on success)
  • Response BodyNotes: JSON 

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

    • Each filegroup in the request body is considered an independent deposit which can be referred to in subsequent requests by the filegroup identifier.
    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 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).

    • 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?

List Deposits

List Deposits

  • Purpose: Retrieves a listing 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
    {
      "depositfilegroup-1-id-1" : {
        "filegroupsfiles" : "",        # Number of filegroupsfiles in deposit
        "filesstatus" : "",        # NumberCurrent of files in deposit
        "status" : ""        # Current deposit deposit status
      },                     # Additional depositsfilegroups listed here
    }


  • Response Code: 200 (on success)
  • Notes:
    • 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 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?
    • will return results for all depositors
      • It may be useful to include a depositor query parameter to allow the 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

Get Deposit Status

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

    Code Block
    {
      "depositfilegroup-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)
  • Notes:
    • It would be possible to retain enough information to be able to provide a tombstone-type response for deposit IDs filegroups which were at some point in the system but have been removed

...

Delete Content

  • Purpose: Allows the repository to ask the Bridge to abort the deposit processRemoves one or more files from DDP storage
  • Request: DELETE POST /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

  • 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
  • Code Block{ "details" : "
  • ",    
  • # 
  • In
  • Checksum 
  • the
  • is 
  • event
  • optional, 
  • of
  • can 
  • a
  • be 
  • rejected
  • included 
  • call,
  • to 
  • information
  • verify 
  • about
  • correct 
  • why
  • file 
  • the
  • is 
  • call
  • being 
  • could
  • deleted
     
  • 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

Restart Deposit

  • Purpose: Allows the repository to ask the Bridge to re-start a deposit that failed. For example, if the repository became unavailable shortly after starting a deposit and the Bridge process failed due to this, or if a single file in the deposit was not in the repository when the Bridge attempted to retrieve it.
  • Request: POST /bridge/deposit/{deposit-id}/restart
  • Response Code: 202 (on success)
  • Notes:
    • Only valid when deposits are in certain failure states (to be better defined as those states are clarified)

Delete Content

  •  "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.
    • 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.
    • Given that the primary unit of preservation is the filegroup, should deletes occur at the filegroup level rather than the file level? This would make the delete action more consistent with the deposit action and would remove the need to mint and manage delete IDs.
    • Is there any reason/need to specify the Filegroup for each file to be deleted? 

List Deletes

  • 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

  • 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
    { 
      "filedelete-id-1-id" : "file-1-checksum",{
        #"files" Checksum: is"", optional, can be included to# verifyNumber correctof filefiles isin beingdelete deletedaction
        "file-2-idstatus" : "file-2-checksum"
    }"     # Current delete status
      },                  # Additional delete actions listed here
    }


  • Response Code: 202 200 (on success)Response Body
  • Notes: 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.
    • 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

...

  • 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
}
    • 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)
    • Delete IDs returned by this method are only those that are in-process.

Get Delete Status

  • Purpose: Allows the repository to ask for status of a content delete action
  • Request: GET /bridge/delete/{delete-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:
    • Need to better define the information that would be provided in the status response

List Deposited Content

  • Purpose: Retrieves a list of all deposited filesgroups and 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
    languagejs
    {
      "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
    { 
    

...

  • 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.

Get Delete Status

...

Response Body: JSON 

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

...

  • Need to better define the information that would be provided in the status response

Abort Delete - ?

Restart Delete - ?

List Deposited Content

  • Purpose: 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
    languagejs
    {
      "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-21-idchecksum",
      },  # Checksum is optional, can be included to verify correct file is                        # 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

...

  • 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"
}
  • 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.
    • Should restores occur at the filegroup level rather than the file level? This could remove the need for minting restore IDs.
    • Given that the primary unit of preservation is the filegroup, should restores occur at the filegroup level rather than the file level? This would make the restore action more consistent with the deposit action and would remove the need to mint and manage restore IDs.
    • Is there any reason/need to specify the Filegroup for each file to be restored?

List Restores

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

    Code Block
    {
      "restore-id-1" : {
        "files" : "",     # List of files in restore 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 restore requests) and the DDP (to determine if there are restore requests which are ready for processing)
    • Restore IDs returned by this method are only those that are in-process.

...

Response Code: 202 (on success)

Response Body: JSON 

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

...

Restore Status

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

    Code Block
    { 
      "files" : "",    # List of files in restore action  
     
    Code Block
    { "status" : "" }   # This could include a top level status or a per-file status (or both)
    }


  • Response Code: 200 (on success)(on success)
  • Notes: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 - ?

...

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

...

  • 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" : ""
    }
    }


  • Given that the primary unit of preservation is the filegroup, should this call be limited to requesting history about filegroups? That limit may be sufficient to allow this call to provide a synchronous response.

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

...

  • Purpose: Allows the DDP to inform the Bridge of a new OTM account. After this call it will be possible for the OTM endpoint Gateway to contact the Bridge.

Update Deposit Status

...

  • Purpose: Update audit index by providing additional audit details

DDP API - Endpoints to be used by the Bridge

Content Ready for Deposit

  • Purpose: A set of content is available for deposit
  • Dropping this call based on the assumption that the DDP will query the Bridge to determine when new deposits are ready (rather than the Bridge notifying the DDP)