...
- 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 { "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
- 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
- The version attribute was added as part of the JSON body on 2019-09-06
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
- 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.
- 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-type
filegroups
: (Optional) Valid values are "all", "filegroups", and "files". Default is "all"Indicates that only filegroup IDs should be provided in the responsefilegroup={}
filegroup
: (Optional) Indicates that only files for this information about a 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 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
- 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.
- 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.
...