Versions Compared

Old Version 22

changes.mady.by.user Bill Branan

Saved on

compared with

New Version 23

changes.mady.by.user Bill Branan

Saved on

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


  • Response Code: 201 (on success)

  • Notes:

    • Each filegroup in the request body is considered an independent deposit which can be referred to in subsequent requests by the filegroup identifier.
    • There is an explicit expectation that the content to be deposited will be available from the OTM Gateway at the path: "gateway-url" + / "filegroup-id" +/ + "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 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.
      • Attempting to deposit a filegroup with a filegroup ID and version that both match a previous deposit will be considered an error and rejected
      • 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).

List Deposits

  • 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
    {
  "filegroup-1-id" : {
    "version : "",       # Version identifier of filegroup
    "files" : "",        # Number of files in deposit
    "status" : ""        # Current deposit status
  },                     # Additional filegroups 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 if there are deposits which are ready for processing) 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(info) The version attribute was added as part of the JSON body on 2019-09-06

Get Deposit Status

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

  • Response Body: JSON

    Code Block
    {
  "filegroup-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 filegroups which were at some point in the system but have been removed

...

  • 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
    {
  "filegroup-1-id" : {
    "version" : "",
    "files" : {
      "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"
    }
  },                                     # Additional filegroups listed here
}


  • Response Code: 202 (on success)

  • Response Body: JSON 

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


  • Notes:
    • 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.
    • (info) The version attribute was added as part of the JSON body on 2019-09-06.
    • It would be possible to allow the 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 restored.

...

  • 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

...

Filegroups

  • Purpose: Retrieves a list of all deposited filesgroups and files. There are 3 list options, (1) List all filegroups and associated files (2) List all filegroups, no files (3) List all files for the specified filegroupfilegroup IDs
  • Request: GET /bridge/list ? {filegroups} & {filegroup}

  • Response Body: JSON

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


List Deposited Filegroup

  • Purpose: Retrieves details about a deposited filesgroup, including all versions and associated files
  • Request: GET /bridge/list/{filegroup-id}
    • filegroup-id : List all versions and files associated with a specific filegroup ID
    • filegroups: (Optional) Indicates that only filegroup IDs should be provided in the response 
    • filegroup={}: (Optional) Indicates that only information about a specific filegroup should be listed

  • Response Body: JSON

    Code Block
    languagejs
    {
  "checksum-type" : ""     # Indicates type of checksums listed below, can be one of: MD5, SHA-256, SHA-512
  "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
    {
      "version" : "",      # filegroup version
      "files" : {
        "file-1-id" : {
           "size" "",      # file size in bytes 
           "checksum", ""  # file checksum
         },
        "filegroupfile-12-id" : {
    # filegroup is a generic grouping of files that can be used to capture structure such as in a digital object or work
"size" "",      # file size in bytes 
           "versionchecksum", : "",  # file checksum
         #}, filegroup version
    "files" : {
      "file-1-id",
  # Additional files  "file-2-id",
listed here
      }
    },                      # Additional filegroups or filegroup versions listed here
}

    or

    Code Block
    { "filegroup-1-id", "filegroup-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
    • (info) The version attribute was added as part of the JSON body on 2019-09-06
     ]
}


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
    {
  "filegroup-1-id" : {
    "version" : "",
    "files: {
      "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"
    }
  },                                     # Additional filegroups listed here
}


  • 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.(info) The version attribute was added as part of the JSON body on 2019-09-06
    • It would be possible to allow the "files" section to be omitted if all files in a given filegroup version are to be restored.
    • 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 restored.

...