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

Compare with Current View Page History

« Previous Version 10 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 for general use

Bridge Details

  • Provides information about the bridge application. Can also be used to verify that the bridge application is available at the expected URL.
  • Request: GET /bridge

  • Response Body: JSON 

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

Bridge API - Endpoints to be used by OTM Gateway

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 

    {
  "object-1-id": {
    "file-1-id" : "file-1-checksum",
    "file-2-id" : "file-2-checksum"
  },
  "object-2-id": {
    "file-3-id" : "file-1-checksum",
    "file-4-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 ? {status}
    • status: (Optional) Limit list to deposits in a specific status

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

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

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 

    {
  "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)
    • Similar to deposits, 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 

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

Abort Delete - ?

Restart Delete - ?


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.

List Restores - ?

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.

Abort Restore - ?

Restart 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

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.

Update Deposit Status

  • Purpose: Allows the DDP to inform the Bridge that a deposit has transitioned to a new status. Certain status updates (such as when a deposit is completed) may trigger additional actions within the Bridge.

Update Restore Status

  • Purpose: Allows the DDP to inform the Bridge that a restore has transitioned to a new status. Certain status updates may trigger additional actions within the Bridge.

Add Audit Events

  • 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)
  • No labels

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