Deposit API brainstorm

From DigiRepWiki

This page is part of Deposit API.

The following list of componenets for a Deposit protocol were brainstormed during the 2-day Deposit meeting. From this list, draft XML seralialistations were produced:

• Deposit API serialisation
• Deposit API explain serialisation
• Deposit API deposit serialisation

This brainstorm document makes the following assumptions:

• Level 0: the repository will have one behaviour; it is mandatory that it describes this behaviour in the explain response. This is configurable by the repository, not the client.
• Level 1: Repository can configure it’s response.

• Mandatory = Level 0
• Mandatory + Optional = Level 1

• Description = human-readable text and/or url

Deposit

• Content:binary CDATA (M)
• Format (O): ID-recommended URI (from the collection being put insterted into)
• TransactionID (O) client-generated identifier for the process
• TargetCollection (O)
• Verbose true||false (O)
• NoOp true||false (O)
• Checksum (O)
• ChecksumAlgorithm (O)
• DepositProperty (O) 0..n string=name of property (repeatable field; each string used for archive-specific information required on deposit)
• TargetState (O)

Explain

ExplainRequest:

• • ID (O) [default=top-level collection]
  • Depth 0||deep||all (O) [default=all]

ExplainResponse:

Wrapper:

• ResponseCode success||fail||depthNotSupported ... [will depend on request]
• Datestamp
• ServerLevel 0||1
• APIVersion 0.1

Response:

Repository:

• ID
• Policy (O) [description, cdata or url]

DefaultCollection

• ID (O)
• Description (O)
  • Depth 0||deep||all (O) [0=all information for default collection and ids of immediate children collections; deep=mixed content; all=all information for all collections]
• DescribeFormat (O) [list additional format(s) (1..n), need vocabularly for formats; one default format (M)]
  • FormatID (O)
  • FormatDescription (O)
• TreatmentDescription (M) [what the repository will do with a deposit, e.g. will it maintain the exact SIP as deposited]
  • PID handling (O) [recommended part of description, how the repository has assigned/handled persistent ids]
• VerboseSupported true||false [for developers - verbose response for a human being for testing/programming]
• NoOpSupported true||false [for developers, facility to 'simulate' put]
• DeleteCodeSupported true||false [for developers mainly, to support provision of a delete code]
• ChecksumAlgorithmSupported default=none [string]
• DepositAllowed true||false
• CollectionPolicy (O) [description, cdata or url]
• DepositProperty (O) set||notSet||setWithString
• TargetStateAvailable
  • ID
  • Description (url or string)

CollectionIDs (depth 0)

• ID (O)

Collections (depth n) (O) [recommended authorised collections only; check OAI treatment of sets]

• ID (O)
• Description (O)
  • Depth 0||deep||all (O) [0=all information for default collection and ids of immediate children collections; deep=mixed content; all=all information for all collections]
• TreatmentDescription (O)
• Format (O)
  • FormatID (O)
  • FormatDescription (O)
• VerboseSupported true||false (O)
• NoOpSupported true||false (O)
• DeleteCodeSupported true||false (O)
• ChecksumAlgorithmSupported default=none [string] (O)
• DepositAllowed true||false (O)

Receipt

Wrapper:

• ResponseCode success||fail
• Datestamp
• ServerLevel 0||1
• APIVersion 0.1

Receipt:

• TransactionID (O) [client-generated identifier for the process]
• IdentifierURI (M) [identfier for the ingested digital object; check Carl Lagoze presentation re this]
  • ObjectURL (O) [the exact digital object deposited, the SIP]
  • DisplayURL (O) [the splash page, jump-off page, metadata record etc.; may not yet resolve to the right thing, e.g. for pending records]
• DepositStatus (M)
  • Accepted (M)
  • Pending (M)
  • Rejected (M)
  • Error (M)
• ErrorCode (M)
  • ErrorContent (O)
  • ErrorParse (O)
  • ErrorChecksumMismatch (O) [required if a checksum is sent]
  • ErrorUnknownChecksumAlgorithm (O) [required if a checksum is sent]
  • ErrorBadRequest (M) [where parameters are not understood]
    • UnknownTarget (O)
    • UnknownDepositProperty (O)
    • IllegalDepositPropertyCombination (O)
• PendingCode (M) [check ISO]
  • PendingActionRequired (O)
    • PendingActionRequiredDescription (O)
    • PendingActionRequiredURL (O) [to continue the process; may or may not require authentication]
    • PendingPreviewURL (O) [user, with authentication if necessary can see what they have deposited]
• ErrorStringDescription (M) [can be an empty string]
• TreatmentDescription (M) [what the repository has done or may have done with a deposit, e.g. policy applied - can be very simplistic]
• FormatHandled (O)
  • ID 0..n (O)
• VerboseDescription (O)
• NoOp (O)
• DeleteCode (O)
• Checksum (O)
• ChecksumType (O) default=MD5

Protocol

For level 0:

• explain request: http get with parameters
• deposit: http post with parameters
• content: binary (name=content)