Versions Compared

Old Version 18

changes.mady.by.user Bill Branan

Saved on

compared with

New Version 19

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" : {
    "file-3-idversion" : "file-1-checksum",
    "files" : {
      "file-43-id" : "file-23-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).

    • This does not currently allow for deposits where files use differing checksum types. Is this a necessary use case?

List Deposits

    • (info) The version attribute was added as part of the JSON body on 2019-09-06
      • Not including "version" in the JSON is acceptable and is functionally the same as "version" : "". This "empty" version is equivalent to any other version.
      • The Bridge and DDP will consider the version value as opaque and not attempt to assign any meaning to the value.
      • Attempting to deposit a filegroup with a filegroup ID and version that both match an previous deposit will be considered an error and rejected

List Deposits

  • Purpose: Retrieves a listing of all in-process 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{
  "filegroup-1-id" : {
    "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" : "",
  "filegroup-1-id  "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:
    • 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.
    • (info) The version attribute was added as part of the JSON body on 2019-09-06

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

...

  • 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 filegroup
  • Request: GET /bridge/list ? {list-typefilegroups} & {filegroup}
    • list-typefilegroups: (Optional) Valid values are "all", "filegroups", and "files". Default is "all"Indicates that only filegroup IDs should be provided in the response 
    • filegroup={}filegroup: (Optional) Indicates that only files for this information about a 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
 work
    "version" : "",       # filegroup version
    "files" : {
      "file-1-id",
      "file-2-id",
    }
  },                      # Additional filegroups or filegroup versions 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 requiredall 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

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 restore status
  },                  # Additional restore 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.

...