You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Notes/Assumptions

  • An account will have a unique identifier or token within the Bridge that corresponds with a set of credentials that provide access to the Bridge API
  • Each account will be created/initialized by the DDP operating the bridge and the credentials needed to access the account will be provided to the account owner
  • There will be a one-to-one relationship between a Bridge account and a single repository (or other) system
  • The repository (or other) system accessing the Bridge will have an internally consistent method for ensuring that File IDs provided to the bridge uniquely identify individual bitstreams presented to the bridge for storage
  • The Bridge application will ensure that each account is provided an independent namespace for File IDs

To Be Determined

  • Method for authentication and authorization. Also need to determine if the same auth methods will be used by the Bridge and the Gateway

Bridge API

Bridge API - Endpoints to be used by OTM Gateway

Bridge Details

  • Provides information about the bridge application
  • Request: GET /bridge

  • Response Body: JSON 

    { 
  "bridge-version" : "",
  "supported-checksum-types" : ""    # Possible values: MD5, SHA-256, SHA-512
}
  • Response Code: 200 (on success)

Register

  • Purpose: Allows a repository with an OTM API to register itself with the Bridge. The information provided in this registration will allow the Bridge to make calls back to the OTM Gateway, such as to pull content listed in a deposit request. This call must be made prior to calls to deposit content. This call may also be made to update the Gateway information.
  • Request: POST /bridge/register

  • Request Body: JSON 

    {
  "gateway-url" : "",      # Endpoint URL where the Bridge can call back to this OTM API
  "gateway-username" : "", # Credentials to allow the Bridge to make calls back into the OTM API
  "gateway-password" : ""  # Credentials to allow the Bridge to make calls back into the OTM API
}
  • Response Code: 200 (on success)
  • Notes:
    • In the event that Gateway information is updated by calling this endpoint again, will those changes be applied to existing or in-process deposit requests?

Deposit Content

  • 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 

    {
  "file-1-id" : "file-1-checksum",
  "file-2-id" : "file-2-checksum",
}
  • Response Code: 201 (on success)

  • Response Body: JSON 

    {
  "deposit-id" : ""
}

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

List Deposits

  • Purpose: Retrieves a listing of all in-process deposits
  • Request: GET /bridge/deposit

  • Response Body: JSON 

    {
  "deposit-id-1" : {
    "files" : "",     # Number of files in deposit
    "status" : ""     # Current deposit status
  },                  # Additional deposits listed here
}
  • Response Code: 200 (on success)
  • Notes:
    • 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 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?

Deposit Status

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

  • Response Body: JSON

    {
  "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

  • 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

    {
  "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

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

  • 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 

    { 
  "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 

    {
  "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.

Delete Status

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

  • Response Body: JSON 

    { "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

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

    { "id-1", "id-2", ... }
  • Response Code: 202 (on success)

  • Response Body: JSON 

    {
  "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. 

  • Response Body: JSON 

    {
  "file-1-id" : {
    "audit-event-1",
    "audit-event-2",
  },
}
  • Response Code: 200 (on success)
  • 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

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 

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

Restore Status

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

  • Response Body: JSON 

    { "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.

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

Add Account

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

Deposit Complete

  • Purpose: Allows the DDP to inform the Bridge that a deposit has completed and no longer needs to be maintained in staging storage.

DDP API - Endpoints to be used by the Bridge

Content Ready for Deposit

  • Purpose: A set of content is available for deposit
  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.